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Tek COMMON LISP Installation 


INTRODUCTION 

This document describes the Tek COMMON LISP distribution. It describes the diskettes, the file 
organization, and discusses how to get COMMON LISP running on your 4400 Series system. 

The software comes on a set of floppy diskettes in relative backup format. To install the 
software, you must create a directory called common-lisp, restore the files using the restore 
utility, then build your COMMON LISP system. 

LOADING THE SOFTWARE 

The following step-by-step procedure assumes that you have not created a file called common- 
lisp on your system. 

1 . Boot your system. 

2. Login as system. 

3. You must be in the root directory ("/"). To insure this type: 

chd / 

4. Create a directory called / common-lisp. To do so type: 

crdir common-lisp 

5. Restore the COMMON LISP files from the distribution diskettes. To do so type: 

restore +ldb common-lisp 

FILE ORGANIZATION 

The organization of the files are as follows: 

/common-lisp: Contains the following directories, sub-directories, and files. 

• README: Describes how to build the makefile. 

• build: Contains files for building a fresh common-lisp. It consists of the 

following: 

Makefile: Contains scripts for making a COMMON LISP executable image. 

ucl.r Contains a mntime system used only for the 4405/4406. 

filesbu Contains all binary files comprising the common-lisp system, 

static.r Contains static portion of the runtime system. 
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• build-4400 

• lib: 

code 

misc 

* / common-lisp! lib! code 
trace.fasl 

step.fasl 

flavors.fasl 

vanilla.fast 

tek-graph.fasl 

foreign.fasl 

cstructs.fasl 

* /common-lisp! lib! doc 
lisp68k.h: 


Contains distribution files similar to those in the build directory 
except the COMMON LISP image created will ran on either the 
4404, 4405, or 4406. 

This directory contains two sub-directories: 

Contains the following files: 

[The trace package] 

[The Stepper] 

[The flavors system] 

[The base flavors system] 

[The 4400 Tektronix Graphics Library] 

[The foreign function interface] 

[Lisp interface to interact with C structures] 

Contains the follwing file. 

C macros for analysing Lisp objects. 


Building a COMMON LISP 

To build a COMMON LISP, follow this procedure: 

1. Restore all the diskettes as describe above. 

2. Read the file called / common- lisp /README. To do so type: 

sys++ make cl. 

It will take a few minutes to create an executable file called /bin/cl. This will be an upper- 
case-insensitive version (the standard version) of COMMON LISP. The file Icommon- 
lisp/README contains details of how to build other case modes and versions of 
COMMON LISP that will ran on the 4404. 

3. Run COMMON LISP. To do so type: 

sys++ cl 

You are now inside the Tek COMMON LISP interpreter. 
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Preface 


The Tek COMMON LISP User Guide and the book, Common Lisp: The 
Language, comprise the Tek COMMON LISP documentation kit Together, they 
describe the language and its use. Common Lisp details the functions and the 
calling conventions of standard COMMON LISP, while the Tek COMMON LISP 
User Guide describes features of this implementation of COMMON LISP: its 
extensions, added features, and peculiarities. We advise the user to read at 
least the following chapters of this document before using Tek COMMON LISP: 


Chapter 1 

Introduction 

Chapter 2 

Implementation 

Chapter 4 

Operating-system interface 

Chapter 5 

Top level 


The Tek COMMON LISP system consists of an interpreter and an optimizing 
compiler. Tek COMMON LISP is a robust and complete implementation of 
COMMON LISP, as specified in Common Lisp. In addition, it has been 
enhanced by a fast, solid implementation of Flavors and a rich, modeless top 
level with extensive intrinsic debugging facilities, and A symmetric interface 
package between LISP and foreign data and procedures (e.g. of C and FOR- 
TRAN). Tek COMMON Lisp was designed to be compact and very fast. It is 
written in COMMON LISP and a special low-level language. 


1 

The 

language 


LISP was one of the first high-level computer languages developed, originating 
in the late fifties, soon after the emergence of FORTRAN. From the beginning 
LISP was a memory-intensive language. For this and less practical reasons, 
LISP was used mostly at universities until the parallel development of inexpen- 
sive fast memory and the nascence of microprocessors in the early eighties 
made it practicable for general use. By that time, LISP had diverged into a 
number of dialects developed at major research centers. With LlSP’s increas- 
ing pervasion, the LISP community felt a concomitantly increasing need to 
standardize the language. This need culminated in the efforts of many people 
to define a new language. Guy L. Steele, Jr. edited the resulting document 


2 

History 


P-1 
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3 

Comments 

and 

suggestions 


4 

Reporting 

bugs 


Common Lisp. The new language, COMMON LISP, combines the features of 
the various dialects of LISP into a single lingua franca of the artificial intel- 
ligence community, now commercial as well as academic. In this process, 
inconsistencies and vagaries of particular dialects were rationalized, making 
COMMON Lisp a ‘cleaner’ language than older LlSPs encrusted with layers of 
tributes to generations of hackers come and gone. The book Common Lisp 
defines the resulting language. Tek COMMON LISP is a complete implementa- 
tion of the COMMON Lisp language as defined in that book, enhanced with 
extensions in important areas such as the top level, error handling, and debug- 
ging, left undefined or vague by the book. This Tek COMMON LISP User Guide 
describes our implementation of COMMON LISP. 


We are always seeking a dialogue with our users in order to improve Tek COM- 
MON LISP. We invite your comments and suggestions. A form is provided at 
the back of this manual for your convenience, but of course personal 
correspondence is always welcome. The address to which to write, either by 
post or by electronic mail, is on the information sheet enclosed with this docu- 
ment. 


We are committed to the highest standards of software engineering. Releases 
of Tek COMMON Lisp are extensively tested both internally and in the field 
before wide dissemination. Nevertheless, as with all, especially new, compli- 
cated computer programs, it is possible that you will find bugs or encounter 
behavior that you do not expect. In that event, we will do our utmost to resolve 
the problem. But, resolving bugs is a cooperative venture, and we need your 
help. Before reporting a bug, please study this document and Common Lisp to 
be sure that what you experienced was indeed a bug. If the documentation is 
not clear, this is a bug in the documentation: Tek COMMON LISP may not have 
done what you expected, but it may have done what it is supposed to do. A 
report that such and such happened is generally of limited value in determining 
the cause of a problem. It is very important for us to know what happed before 
the error occured: what you typed in, what Tek COMMON LISP typed out. A 
literatim log, preferably hard copy, may be needed. If you are able to localize 
the bug and reliably duplicate it with a minimal amount of code, it will greatly 
expedite repairs. It is much easier to find a bug that is generated when a single 
isolated function is applied than a bug that is generated somewhere when an 
enormous application is loaded. Although we are intimately familiar with Tek 
COMMON Lisp, you are familiar with your application and the context in which 
the bug was observed. Context is also important in determining whether the 
bug is really in Tek COMMON LISP or in something that it depends on, such as 
the operating system. 

To this end, we request that your reports to us of bugs or of suspected 
bugs include the following information. If any of the information is missing, it 
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is likely to delay or complicate our response. 

• Lisp implementation details. Tell us the implementation of Tek COMMON 

LISP that you are using, including at least the release number and date of 
release of Tek COMMON LISP, the manufacturer, model, and version of 
the hardware on which you are running Tek COMMON LISP, and the 
operating system and its release number. The minimum information we 
need can be provided by executing the following functions within Tek 
COMMON LISP: lisp-implementation-type, lisp-implementation- 

version, machine-type, machine-version, software-type, software- 
version, and short-site-name. 

• Information about you. Tell us who you are, where you are and how you 
can be reached (an electronic mail address if you are reachable via Inter- 
net or Usenet, a postal address, and your telephone number), your Tek 
COMMON Lisp license number, and in whose name the license is held. 

• A description of the bug. Describe clearly and concisely the behaviour 
that you observe. 

• Exhibits. Provide us with the smallest, self-contained LISP source frag- 
ment that will duplicate the problem, and a log (e.g. produced with the 
dribble function) of a complete session with Tek COMMON LISP that 
illustrates the bug. 

A convenient way of generating at least part of a bug report is to use the drib- 
ble function in Tek COMMON LISP. (The function is described in §25.3, p. 443 
of Common Lisp.) First type (dribble filename) to record the remainder of the 
session in file filename. Then apply the functions that were described earlier to 
describe your implementation of Tek COMMON LISP. Next duplicate your bug. 
And then type (dribble) to end the log. Note that if what you type to duplicate 
the bug loads in files either directly or indirectly, attach a complete listing of 
the source version of these files to your session log. The following dialogue 
provides a rudimentary template for the kernel of a bug report. 

<cl> (dribble "bug. dribble" ) 

<cl> (lisp-implementation-type) 

<cl> (lisp-implementation-version) 

<cl> (machine-type) 

<cl> (machine-version) 

<cl> (software-type) 

<cl> (software-version) 

<cl> (short -site -name) 

<cl> ;; Now duplicate your bug . . . 

<cl> (dribble) 

Send bug reports to either of the electronic mail or postal addresses that are 
given on the information sheet that is enclosed with this document. In general 
an electronic report can be acted upon more speedily. When we receive your 
bug report, it will be assigned a number by which we can mutually refer to it 
concisely and unambiguously, and you will be sent a receipt. We will 
investigate the report and inform you of its resolution in a timely manner. 
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We will meet you more than half way to get your project moving again 
when a bug stalls you. We only ask that you take a few steps in our direction. 


5 

Keeping 

abreast 


We maintain mailing lists, both by post and by electronic mail. We also main- 
tain an electronic mail forum, accessible via Internet and Usenet, for users of 
Tek COMMON Lisp. You are invited to subscribe to our mailings and to 
become a member of our electronic forum. We like to hear about what our 
customers are doing with Tek COMMON LISP, and we can keep you abreast of 
new releases and other pertinent information. The addresses appear on the 
information sheet enclosed with this document. Join us! 
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1 Introduction 


This document is a user guide designed to supplement Common Lisp: The 
Language (Guy L. Steele, Jr., Digital Press, 1984). It describes Franz 
Incorporated’s Tek COMMON LISP implementation of the COMMON LISP 
language. This introduction describes the format of this manual, presents an 
outline of its contents, and introduces other documents that will be useful to 
you. And to get you started, it also explains how to enter and exit Tek COM- 
MON LISP and how to compile functions. We urge users to read this chapter 
and at least chapters 2, 4, and 5 before using Tek COMMON LISP. 

This document is a reference manual. Neither it nor Common Lisp are pri- 
mers to COMMON Lisp nor introductions to the language. The user is 
encouraged to consult textbooks on LISP such as COMMON LISP craft (Robert 
Wilensky, W. W. Norton and Company, 1986) to gain familiarity with the 
language. We assume that you are familiar with at least one dialect of LISP. 


This document is divided up into several chapters describing how we imple- 
mented features either not described in Common Lisp or not specified exactly 
in Common Lisp. We have tried to follow the format of Common Lisp, where 
possible. The format is described in detail in §1.2.5 of Common Lisp. Briefly, 
definitions of functions, variables, named constants, special forms and macros 
appear on their own line in a special type font and in the following form: 


1.1 

Format of 
the manual 


name parameters [Type] 

For example: 

digit-char-p char &optional (radix 1 0) [Function] 

*default-pathname-defau!ts* [Variable] 

sett {place newvalue}* [Macro] 

As in Common Lisp, definitions may spill over onto additional lines, and are 
followed by explanation and examples. 

Type faces are used to distinguish between functions, symbols, constants, 
printed forms, and examples. Functions are printed in bold gothic. Other 

symbols are printed in gothic. Constants (such as 0, #71, "A", or nil ) and spe- 
cial symbols (such as *package *) are printed in italic gothic. Keywords and 
lambda-list keywords (such as :test and &optional, respectively) are indicated 
in bold italic gothic. Printed forms are printed in italic gothic. Examples in 
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1.2 

An outline of 
the manual 


1.3 

Other 

documents 


the text are printed in gothic. When examples appear separate from the text, 
output from the Tek COMMON LISP system is printed in courier; input to 
Tek COMMON Lisp is printed in bold courier; and comments are printed 
in italic courier. 


This document contains the following chapters: 

1 This Introduction. Included below is information on how to start (and 
exit) Tek COMMON LISP and how to compile files. 

2 Implementation. This chapter describes in detail this implementation of 
the COMMON Lisp language, with sections on data types, storage alloca- 
tion, pathnames, the compiler, and internal functions. It also includes 
some advice for writing portable COMMON LISP code. 

3 Extensions. This chapter describes some of the extensions to COMMON 
LISP found in Tek COMMON LISP, including the error-handling facility 
and search lists. 

4 Operating-system interface. Described here are facilities to access 
operating-system information, such as running subprocesses, getting 
command-line arguments, and changing directories. All of these facilities 
are extensions to COMMON LISP. 

5 Top level. The top level is the user’s interface with Tek COMMON LISP. 
It includes the debugger, tracer, and inspector. 

6 Flavors. Flavors is an object-oriented language extension that is part of 
Tek COMMON Lisp. Our implementation of Flavors is essentially compa- 
tible with Symbolics ‘Genera 6’ Flavors. 

7 Profiling. This chapter describes the profiler, a tool for analyzing resource 
consumption in your LISP applications. 

8 Foreign functions. This chapter describes our interface between LISP and 
other languages such as C or FORTRAN. 

9 Packages. This chapter describes the packages that are part of Tek COM- 
MON LISP. 

A Summary of symbols. This is an appendix that enumerates all of the sym- 
bols that are described in this Guide. Functions, macros, and special 
forms are described by a template that lists the arguments. 

This document comes in several flavors, each targeted for different machines. 


Along with this document and Common Lisp, you should have received an 
installation guide. Release notes and any supplements described above are 
bound in with this document. Most of Tek COMMON LISP is described in Com- 
mon Lisp. You should refer to that book for most information on the func- 
tionality of Tek COMMON Lisp. This User Guide describes our implementa- 
tion of COMMON Lisp. Here you will find implementation-specific details, cla- 
rifications of Common Lisp, and descriptions of extensions (features beyond 
the scope of the specification in Common Lisp) such as ‘Flavors’ (chapter 6) 
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and profiling (chapter 7). 

New users should install their system following the instructions in the 
installation guide. Once the system has been successfully installed, there 
should be no reason to refer to the installation guide again. It should be kept, 
however, in case you must reinstall the system for any reason. 

We recommend that you at least scan most of this manual before seriously 
using Tek COMMON LISP. Also, look over the release notes, which list features 
(and problems) that affect this release. Common Lisp should be your main 
reference manual. Tek COMMON LISP implements the language as described 
in that book. We would appreciate any comments you have about the docu- 
mentation, its completeness, ease of use, or clarity. You may send comments 
to the address listed on the information sheet included with this document. 


The installation procedure ends with the building of a file named cl. The exact 
location of this file will depend on your machine configuration. Let us assume, 
however, that the file is in a directory contained in your search path (e.g., 
lusr/local ). To get into Tek COMMON LISP, just type 

% cl 

There will be a short wait while Tek COMMON LISP is being loaded and initial- 
ized. Then you should see the Tek COMMON LISP banner and the prompt, 
which looks like 

<cl> 

At this point, you are in the LISP environment and have all of COMMON LISP at 
your disposal. 

If you have insufficient swap space, LISP may exit with an error message 
indicating that the swap space is too small. In that case, either kill other 
processes or increase the size of your swap space, and then start Tek COMMON 
LISP again. (If you find it necessary to increase your swap space, refer to your 
operating-system documentation.) 


1.4 

How to run 
Lisp 


Common Lisp is silent on the question of how to exit LISP. Tek COMMON LISP 
has several commands which will cause a LISP session to terminate. The sim- 
plest is the function exit. The expression 

(exit) 

will cause the current LISP image to exit. (This function is described in §4.3, 
Image functions.) One can also exit LISP directly from the top level, using the 
top-level command :exit, documented in chapter 5. 


1.5 

How to exit 
LISP 
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1.6 

How to 

compile 

functions 


COMMON Lisp provides two ways to compile functions. The first is to define 
the function in the interpretive environment and then call the compile function. 
The second way is to write the function to a file either with an editor or some 
other means, and then call the compile-file function. For example, suppose 
you have the function foo defined already in your LISP environment, then to 
compile it, just type 

(compile ’foo) 

which will replace the interpreted version of foo with the compiled version of 
foo. If you want to compile a whole file (say foofncs.cl) full of functions, you 
can use the function compile-file as follows 

(compile-file "foofncs.cl") 

which will result in a new file being created in foofncs.cl ' s directory called 
foofncsfasl. This file can then be loaded into your LISP environment (with 
either the load function or with the :ld top-level command), and you will then 
have all of foofncs’s compiled functions at your disposal. 
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Tek COMMON LISP contains all of the required COMMON LISP data types plus 
an instance data type for use by the flavors system. Fixnums are signed 29-bit 
quantities. Bignums may be as large as 2 1 ’ 048 ’ 576 . There are two distinct 
floating-point types. Short-float and single-float are equivalent and are 32-bits 
wide. Double-float and long-float are equivalent and are 64-bits wide. The 
distinct array data types are the following: 


(array t) 

(array bit) 

(array (unsigned-byte 8)) 

(array (unsigned-byte 1 6)) 

(array (unsigned-byte 32)) 

(array string-char) 

(array single-float) 

(array double-float) 

(array (signed-byte 8)) 

(array (signed-byte 16)) 

(array (signed-byte 32)) 

(array fixnum) 

(simple-array t (*)) 

(simple-array bit (*)) 

(simple-array (unsigned-byte 8) (*)) 
(simple-array (unsigned-byte 16) (*)) 
(simple-array (unsigned-byte 32) (*)) 
(simple-array single-float (*)) 
(simple-array double-float (*)) 
(simple-array (signed-byte 8) (*)) 
(simple-array (signed-byte 16) (*)) 
(simple-array (signed-byte 32) (*)) 
(simple-array fixnum (*)) 


2.1 

Data types 
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2.2 

Storage 

allocation 


2.3 

Pathnames 


2.3.1 

Parsing 

pathnames 


Tek COMMON Lisp uses a two-space, copying garbage collector. Data objects 
which cannot move or are unlikely to become garbage are placed in a special 
static storage area. 

excl:*gcprint* [Variable] 

■ If the variable *gcprint* is not nil, then when garbage collection is 
started a message will be printed on the terminal, and after it is complete 
another message will be printed describing the current state of storage 
allocation. It prints the statistics in this form: alb(c), where is a is the 
number of bytes of dynamic space is use, b is the sum of the dynamic 
space in use and the dynamic space free, equalling the total number of 
dynamic bytes available to the process, and c is the total number of static 
space bytes allocated. 

excl:gc [Function] 

■ This will cause a garbage collection to occur. A garbage collection 
will occur automatically whenever the free space is exhausted. 


COMMON Lisp pathnames do not always map easily into operating-system 
filenames. In this section we describe the mapping chosen for Tek COMMON 
LISP on the Unix operating system. 


The host and version components of pathnames are ignored. 

The directory, name, and type fields are determined from a namestring as 
follows: If there are no slashes in the namestring, then the directory component 
is nil. If there are slashes then all characters from the beginning of the name- 
string to, but not including, the last slash in the namestring is the directory 
component. The one exception is that if there is just one slash and it is at the 
beginning of the name, then the directory component is 7". After removing the 
directory component and the following slash from the namestring, the rest of 
the string determines the name and type components. If the rest of the string is 
empty then both components are nil, otherwise, the name contains everything 
up and excluding the last period in the string. The characters following the 
period are the type. If the name ends in a period, then the type is the empty 
string. The exceptions are for names beginning with a period. In this case the 
period is being used to hide the file from the directory listing program, not to 
separate the name and type components, thus a leading period is treated as a 
non-period character. The string is treated specially and is parsed as a 
name of and a type of nil. The following table has some examples of path- 
name parsing: 
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Pathname components 


Namestring 

Directory 

Name 

Type 

it jtt 

ryrr 

nil 

nil 

7 foo" 

ryrr 

"foo" 

nil 

"/foo." 

ryrr 

"foo" 

rrrr 

Vfoo.b" 

ryrr 

"foo" 

"b" 

"/foo. bar." 

ryrr 

"foo.bar" 

rrrr 

7foo.bar.baz" 

ryrr 

"foo.bar" 

"baz" 

"/foo. .bar" 

ryrr 

"foo." 

"bar" 

"foo.bar" 

nil 

"foo" 

"bar" 

"foo/" 

"foo" 

nil 

nil 

"foo/bar" 

"foo" 

"bar" 

nil 

"foo/bar/baz” 

" foo/bar " 

"baz" 

nil 

"foo/bar/” 

"foo/bar" 

nil 

nil 

".lisprc" 

nil 

".lisprc" 

nil 

"x.lisprc" 

nil 

"X" 

lisprc" 

rr rr 

nil 

rr rr 

nil 

it it 

nil 

rr rr 

nil 

it rr 

nil 

rr rr 

rrrr 


Table 2.1. Examples of conversions of namestrings to path- 
names. 


Merging of pathnames is handled specially by Tek COMMON LISP on the Unix 
operating system to take advantage of directory hierarchies. 

Given two pathnames a and b, then the result (c) of merging these path- 
names may cause merging of their directory components. 

(sett c (merge-pathnames a b)) 

If pathname a does not have a directory component, then the directory com- 
ponent of pathname b becomes the directory component of the result c. If 
pathname a ’ s directory component is absolute (i.e. it begins with a slash "/") 
then pathname c will have pathname a’s directory component. 

If pathname a has a directory component that is relative, then the directory 
component of pathname c depends on the directory component of pathname b. 
If pathname b has a relative directory component, then c’s directory component 
will be the same as a’s. If b’s directory component is absolute, the relative 
directory component of pathname a is appended to the absolute component and 
the result is canonicalized to eliminate such components as and For 
example if pathname b’s directory component is "A foo" and pathname a’s direc- 
tory component is "./bar", then pathname c’s directory component will be 
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Merging 

pathnames 


Tektronix, Inc. 

2-4 Implementation 


2.4 

The compiler 


2.4.1 

File types 


"/ foo/bar". Finally, if pathname b does not have a directory component, the 
directory component of pathname a becomes c’s directory component. 

There are several implementation-dependent facets to a COMMON LISP com- 
piler. These include the naming of source and object files, and how declara- 
tions are handled and optimizations are performed. 


The default source-file type in Tek COMMON LISP is "cl". The default 
compiled-file type in Tek COMMON LISP is "fast”, which is a mnemonic for 
‘fast-loadable’ file. The default source-file type may be changed to suit your 
preferences. 

The variable system :*source-file-types* is a list of pathname types of 
COMMON Lisp source files. The default value of this variable is ("cl"). This 
means that if no file type is specified for the argument of compile-file (or the 
top-level command :cf) the file type "cl" will be assumed. For example 

(compile-file "too") 

will cause the compiler to first look for the file foo. cl. If this file is not found, 
then the compiler will search for foo. 1 Some users prefer to use "lisp" as a 
source file type instead of "cl”. 

(setq system:*source-file-type* ’("cl” "lisp")) 

will cause the compiler to look for files with file type "lisp" as well as "cl". 
Then 


(compile-file "foo") 

will look for foo. cl, foo. lisp, and foo in that order, and compile the first file 
found. 

An element of system:*source-file-types* may be nil, denoting a file 
name with no type. For example, a value of (nil "cl") will cause (compile-file-if- 
needed "bar") to look first for bar then for bar. cl. 

Users who change system:*source-file-types* may also wish to change 
system:*load-search-list* and system:*require-search-list* so that the func- 
tions load and require will look for files with the desired file types as well. 
See §3.3, Search lists, for a description of these variables. 


1 Refer to §2.3, Pathnames, in this chapter for a description of how Tek Common Lisp parses 
Unix namestrings and merges Unix pathnames. 
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The compiler generates code which, in addition to carrying out the tasks 
required by the LISP code, checks that input is of the correct type, allows for 
profiling and facilitates debugging, and checks for interrupts. This additional 
code is fast and small, but of necessity somewhat reduces the speed and 
increases the size of the compiled code. Users can control the amount of this 
extra code that is produced with the options specified below. The first line of 
control is to set the safety, size and speed options. The descriptions below 
show how values of safety, size and speed affect code generation. The values 
run from 0 to 3 for safety, size and speed, with 0 representing the least concern 
for safety, size and speed, and 3 representing the greatest concern. The user 
can control the level of safety, size and speed by using the proclaim function, 
as follows: 

(proclaim ’(optimize (safety nl ) (size n2 ) (safety n3))) 

where nl , n2 and n3 are integers from 0 to 3. The following variables define 
what the various settings of safety, size and speed do. They are bound to func- 
tions which return f or nil for the given settings of safety, size and speed. Note 
that with the current definitions, the setting of size does not affect the code 
generated by the compiler. The user may change the definitions so that size is 
relevant. The code for changing the settings is given after the definitions. 

compiler:declared-fixnums-remain-fixnums-switch [ Variable ] 

■ Bound to a function which, given safety, size and speed, returns f if the 
compiler should assume that the sum and the difference of arguments 
declared to be fixnums will result in a fixnum. By default, returns t if 
speed is greater than 2 and safety is less than 2. 

compiler:generate-call-count-code-switch [Variable] 

■ Bound to a function which, given safety, size and speed, returns t if the 
compiler should generate call-counting code. Call counting is used only 
by the profiler. Its overhead is small, however, so it is recommended that 
it be done. By default, returns t unless speed is set to 3. 

compiler:generate-interrupt-check-switch [Variable] 

■ Bound to a function which, given safety, size and speed, returns t if the 
compiler should generate code to check for asynchronous interrupts (like 
control-C from the keyboard.) If this check is not made, there is no way to 
stop LISP and regain control if the program goes into an infinite loop. By 
default, returns t unless speed is set to 3. 
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compilentrust-declarations-switch [Variable] 

■ Bound to a function which, given safety, size and speed, By default, 
returns t if declarations the user provides should be trusted without verify- 
ing them at runtime. By default, returns t when speed is greater than 
safety. 

compiler:verify-argument-count-switch [Variable] 

■ Bound to a function which, given safety, size and speed, returns t if the 
compiler should generate code to verify that the correct number of argu- 
ments have been passed to a function. Note: if the wrong number of argu- 
ments are passed to a function without detection, the consequences can be 
fatal to LISP. Argument checks are always done if there are &optional or 
&rest arguments. By default, returns t is speed is less than 3 or safety is 
greater than 0. 

com pi le r:verify-car-cd r-switch [ Variable ] 

■ Bound to a function which, given safety, size and speed, returns t if the 
compiler should generate code to verify that the type of an object whose 
type is undeclared is a list before doing a car or cdr of the object. By 
default, returns t for speed less than 3 or safety greater than 1. 

compiler:verify-non-generic-switch [Variable] 

■ Bound to a function which, given safety, size and speed, returns f if the 
compiler should generate code to verify that the type of an object whose 
type is undeclared is of the correct type when the object appears as an 
argument to a non-generic function, (e.g. svref). By default, returns t for 
speed less than 3 or safety greater than 1 . 

compiler:verify-symbol-value-is-bound-switch [Variable] 

■ Bound to a function which, given safety, size and speed, returns t if the 
compiler should generate code to detect that a symbol’s value is bound 
before that value is used. By default, returns t for speed less than 3 or 
safety greater than 1 . 

The user may change the safety, size and speed values that trigger these vari- 
able settings in the following way. 

(setq var #’(lambda (safety size speed) 

(declare (ignore size)) 

(logical-form))) 

where (logical-form) is nil or t as a function of safety, speed and size. 


D-oi-tms 



Tek COMMON LISP 
Implementation 2-7 


Thus, if the following code is executed, the compiler will not generate call 
counting code for speed set greater than 1 of safety set less than 1 or size 
greater than 1 . 

(setq compiler:generate-call-count-code-switch 
#’(lambda (safety size speed) 

(cond ((> speed 1 ) nil) 

((< safety 1) nil) 

((> size 1) nil) 

(tt)))) 

Safety, size and speed all have default value 1 . 


Certain top-level forms are evaluated by the compiler in its execution environ- 
ment 2 in addition to being otherwise processed normally. The functions below 
are all evaluated by the compiler when seen at top level. 


2.4.3 

Top-level 

forms 


make-package 

in-package 

shadow 

shadowing-import 

export 

unexport 

use-package 

unuse-package 

import 

require 


In effect the functions above are treated as if they were surrounded by (eval- 
when (compile eval load) ...). Among these functions, only require is not 
explicitly mentioned in § 1 1.7 of Common Lisp. 


Users trying to debug code will often have occasion to look at the stack for 
recent function calls. There, one may find, instead of *, +, <, etc., oddly named 
functions of the form: 

string _2op 
string _3op 

where string is *, +, <, etc. These functions are called for compiler efficiency, 
and should be interpreted as the functions named by string. Thus, for 

2 This is referred to in Common Lisp as processing the form in compile-time-too mode. Cf. 
§§11.7 and 5.3.3. 
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example, <_2op should be interpreted < (i.e. the not-greater predicate). 


2.6 

A note on 
portability 


COMMON LISP code written without implementation-dependent extensions 
(that is using the language strictly as described in Common Lisp ) should in 
theory be portable across various implementations and machines. In practice, 
however, true portability is rarely achieved, and it is likely that Tek COMMON 
LISP code will not port to other COMMON LISP implementations without at 
least some effort. The reasons for this include the following. 

• Use of implementation-dependent features. Most large programs will use 
some implementation dependent features. These will not, of course, port 
to other implementations of COMMON LISP. Tek COMMON LISP allows 
users to isolate almost all implementation dependent features by placing 
them in the excl and implementation independent features in the lisp 
package. See chapter 9 for further discussion of the packages in Tek 
COMMON LISP. 

• Use of extensions. Extensions are really implementation-dependent 
features; however, they are distinct in that they involve functions, macros, 
or variables defined in Common Lisp. Because of this, the symbols will 
not be isolated by the package system. In Tek COMMON LISP all exten- 
sions are upward-compatible. In Release 1.4, the only function that has 
been extended is load. It takes additional keyword parameters that facili- 
tate the loading of foreign code. Its behaviour when used to load LISP 
code complies with the specification in Common Lisp. 

• Latitude in interpretation or laxity of specification. The standard as 
described in Common Lisp is very complex. Implementors may in good 
faith interpret specifications in incompatible ways. Usually, the confusing 
specifications concern declarations and scoping issues. Until there is a 
nationally defined standard (with publically available validation tests) dif- 
ferent implementations of COMMON LISP will certainly differ on certain 
arcane features. 

We have striven to produce a correct implementation of the COMMON LISP as 
described in Common Lisp, and have then added those extensions which we 
feel are useful to users. Our experience porting code written for other imple- 
mentations of COMMON LISP have not shown any great difficulties. We 
encourage our users to report any problems they have porting COMMON LISP 
code. 
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3 Extensions 


Common Lisp is purposefully incomplete in some areas. An interface to 
foreign functions is not specified, nor are a top level and an error-handling 
mechanism. Foreign functions and the top level are left out because they are 
very system dependent; error handling because there was no agreement on 
what should be done when Common Lisp was published (and there still is not 
as of this writing, November 1986). We have provided extensions to COMMON 
LISP in all these areas. Error handling is documented in this chapter, foreign 
functions in chapter 8 and the top level in chapter 5. Users should be aware 
that these extensions are not portable across implementations of COMMON 
Lisp. 

We have added some further extensions, including functions or capabili- 
ties that we believe make COMMON LISP easier to use. Among these are case 
sensitivity, a ‘keyword-oriented’ conditional construct, and additional type- 
checking functions. These extensions are documented in this chapter. 

Again, the user is cautioned that taking advantage of these extensions will 
produce code that is not portable across implementations. Chapter 9 discusses 
the how symbols in Tek COMMON LISP are dispersed among several packages, 
and how the user interested in portability can best achieve it using packages. 


In standard COMMON LISP, the reader converts all unescaped lowercase char- 
acters to uppercase, so that for example Foo and too are both read as FOO. 
This is a sign of the age of the LISP programming language. When LISP was 
invented in the sixties, most terminals could only handle uppercase. When 
lowercase terminals started to appear, most operating systems and languages 
were modified to simply map lowercase characters to uppercase and then 
proceed as before. Some modem programming languages (C, Smalltalk, 
Modula-2, Newspeak) distinguish between uppercase and lowercase in identif- 
iers and programmers use this distinction to great advantage. In C, constants 
are usually in uppercase and variables in lowercase. In Smalltalk, capitaliza- 
tion is used to distinguish words in multi-word identifiers, and to classify iden- 
tifiers. The excl:set-case-mode function can change Tek COMMON LlSP’s 
reader so that the case of characters in identifiers is significant. 

There are two parameters that determine the reader’s actions: case prefer- 
ence and case sensitivity. The preferred case is either upper or lower, and 
refers to the case of the characters in the print names of all of the standard sym- 
bols, such as car and cdr. Case sensitivity is either sensitive or insensitive. 


3.1 

Reader case 
modes 
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Case-sensitive means that the reader doesn’t modify the case of any characters 
it reads. Case-insensitive means that characters that are not of the preferred 
case are converted to the preferred case. 

There are four possible values for the combination of case preference and 
case sensitivity. 

• Case-insensitive, uppercase-preferred. This is the mode used in standard 
COMMON Lisp and in most of the older LlSPs such as MacLlSP. With this 
mode you can even enter LISP programs with a card punch. 

• Case-sensitive, uppercase-preferred. This is the mode used by InterLlSP. 
This is perhaps the most difficult mode to use since you have to hold the 
shift key down to type the names of system functions, or else they won’t 
be recognized. 

• Case-insensitive, lowercase-preferred. This mode is very similar to the 
case-insensitive, uppercase-preferred mode. 

• Case-sensitive, lowercase-preferred. This is the mode use by FRANZ LISP 
(and the C programming language). It matches the conventions of the 
UNIX and UniFLEX operating systems, and thus is the most natural mode 
to use for some programmers. 

The function excl:set-case-mode and two variables excl:*current-case- 
mode* and excl:*ignore-package-name-case* are provided for controlling 
and sensing case modes. 

exckset-case-mode new-mode [Function] 

■ new-mode is one of the four keywords: :case-insensitive-upper , 
:case-insensitive-lower, :case-sensitive-upper, and :case-sensitive- 
lower. Function set-case-mode converts LISP to use the new mode for 
subsequent reading and returns a keyword denoting the previous mode. 
This function must do quite a bit of consistency checking when changing 
between modes with different case preferences, and may may take as long 
as several minutes to complete. Below we go into more detail on the 
operation of exc I : set-case-mode and the implications on compatibility. 

excl:*current-case-mode* [Variable] 

■ The value of this variable is the keyword denoting the current mode. 
This variable should be considered read-only, it is changed by exckset- 
case-mode to reflect the current mode. Its initial value is ; case- 

insensitive-upper. 

excl:*ignore-package-name-case* [ Variable ] 

■ If this value is true, then the case of characters in single-case package 
names and nicknames is ignored by the reader when looking up qualified 
symbols. This variable is initially nil, but the user may find it useful to 
give this variable a non- nil value if he chooses to operate in one of the 
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case-sensitive modes. This is described in more detail below. 


Initially the reader is in :case-insensitive-upper mode. If the user executes 
(set-case-mode :case-sensitive-upper), the set-case-mode function need only 
inform the reader not to alter the case of characters it reads, and inform the 
printer that lowercase characters needn’t be escaped on output. If the user 
wants to change the mode to one of the lowercase-preferred modes, then much 
more work must be done. Every (interned) symbol’s printname is examined. 
If the print name does not contain characters of different cases, then the print 
name is converted to the new preferred case (in this example, lowercase). If 
the print name contains characters of different case then it isn’t modified at all. 
If converting a symbol’s print name to lowercase would cause there to be two 
symbols with the same print name in the same package, then no conversion is 
done for the symbol. Similarly, the names and nicknames of packages are con- 
verted to the new preferred case if the names do not contain both lowercase and 
uppercase characters. After excl:set-case-mode has examined and converted 
as many symbols as possible, it prints a list of those symbols that could not be 
converted due to mixed case or a symbol conflict. 

The version of Tek COMMON LISP that you receive will work in any 
mode. We expect that most users will either choose to use Tek COMMON LISP 
in its standard :case-insensitive-upper mode or choose to use :case- 
sensitive-lower mode. The first group can simply use LISP as distributed and 
ignore everthing about case modes. The second group should execute the 
exc!:set-case-mode function, create an image with exckdumplisp and use 
that LISP. In order to load or compile source code written assuming the stan- 
dard :case-insensitive-upper mode, the second group should use exckset- 
case-mode to put LISP in :case-insensitive-lower mode. It is much faster to 
go from ".case-sensitive-lower mode to :case-insensitive-lower mode, than 
to :case-insensitive-upper mode, and the two insensitive modes are nearly 
equivalent in their effect. 


Changing the case of identifiers or making LISP case-sensitive is not an 
upward-compatible change to LISP. Thus the user must weigh the advantages 
of a more ‘modem’ LISP syntax against possible future drawbacks, such as not 
being able to run the code in other versions of COMMON LISP. We examine the 
possible compatibily problems. 


None of the standard Tek COMMON LISP code depends on the case of the char- 
acters in identifiers, and it is unlikely that future code will. Packages are unfor- 
tunately referred to by strings and thus compatibility problems can crop up. 
The excl:set-case-mode function will convert the case of package names to 
the preferred case. However, if lowercase is the preferred case and the user 
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3.1.4 

Compiled 

code 


3.2 

Errors 


types (in-package "LISP") then this will create a new package LISP distinct 
from the existing lisp package. There are two solutions to this problem. One is 
to set the excl:*ignore-package-name-case* variable to t. In this case, when 
in-package looks for and doesn’t find a package named LISP, it converts it to 
lisp and then finds the package. If in-package is given a name containing 
uppercase and lowercase characters, then even if excl:*ignore-package-name- 
case * is t, it will not convert it to the preferred case. For example, (in- 
package "Lisp") will fail to match the package named lisp. The second solu- 
tion to this problem is to always use symbols when referring to packages, i.e. 
use (in-package ’lisp). This expression will refer to the lisp package in all 
modes except :case-sensitive-upper. 

When a file is compiled, the case-mode setting at the beginning of the compila- 
tion is stored in the fas l file. If the preferred case when a file was compiled is 
different than than when it is loaded, the fast loader will do case conversion on 
the fly to those symbols whose print names which do not have both lowercase 
and uppercase characters. 


Tek COMMON Lisp provides a primitive error-handling facility in the form of a 
single function exckerrorset. When the COMMON LISP standard specifies an 
error-handling system, this function may be obsoleted. The exckerrorset 
function evaluates an expression and devours any errors that might arise; it 
regurgitates a Boolean value indicating whether it got an error to feed on or 
not. 

excl:errorset form [announcep] [Macro] 

■ The expression form is evaluated, and if no errors occurred then the 
first value returned from errorset will be t, and the rest will be the values 
returned from the evaluation of form. If an error occurs, then the single 
value nil is returned. If announcep is non-nil, then the error message 
associated with the error will be printed, otherwise nothing is printed. 
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The functions require and load (and the equivalent top-level command :ld) 
read files. The COMMON LISP standard specifies how the file-name argument 
to these functions is processed to yield the true name of the file to be read: the 
argument is merged (using merge-pathnames) with the value of *default- 
pathname-defaults *. 1 The value of *default-pathname-defaults* is usually the 
pathname of the directory in which LISP is being run. This file-finding 
mechanism is inadequate for all but the simplest of applications. 

Addressing the need for a more flexible file-finding mechanism, Tek 
COMMON Lisp incorporates search lists, data structures embodying informa- 
tion about how the functions load and require will find a file to load into LISP. 
Each function uses its own search list. 

Search lists permit the user to specify a sequence of pathnames to be 
merged with the file-name argument to load or require. We henceforth refer 
to this file-name argument as the supplied name. From among those path- 
names resulting from the sequence of merging operations, the one pathname 
that satisfies the given criteria will be loaded. Further, it is possible to specify 
side effects, e.g. to compile a file if the source file has been modified or 
created more recently than the corresponding compiled {fast) file. This very 
general mechanism provides considerable control over file-loading operations. 


A search list is a recursive data structure. It may be a symbol, string, path- 
name, or a list of search lists. (The car of a list is interpreted specially.) The 
elements of a search list are processed sequentially. If the search list is recur- 
sive, it is processed in depth-first fashion. The goal of processing a search list 
is to locate a file to be loaded — in effect a search list ‘returns’ the pathname of 
a file. It is often convenient to refer to search lists as returning a pathname, 
especially when discussing recursive search lists . 2 It is an error if a file cannot 
be located within the given constraints. 

• Symbols. If the symbol is bound, then its value is interpreted as a search 
list. If the symbol is unbound, it is ignored. If the symbol is nil, the 
denoted file is simply the file-name argument to load or require. 

• Strings and pathnames. The file denoted by merging the string or path- 
name with the supplied name. If search-element is a string or pathname 
search list, the denoted file will be 


1 Note that this merging operation effectively fills in the missing components of an incomplete 
file-name specification from the corresponding components of *default-pathname-defaults*. 
If a file-name argument to require or load already unambiguously identifies a file to be read, 
the merging operation is superfluous. In Tek Common Lisp, a file name must be an absolute 
UNIX pathname and specify a file ‘type’ to be unambiguous in this context (See §2.3, Path- 
names, for further information.) 

2 In reality of course, a function is being applied recursively to a search list and it is this func- 
tion that is returning a pathname. 
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(merge-pathnames supplied-name search-element) 

• Lists. The car of the list determines how the elements of the list are pro- • 
cessed. The car may be a keyword or a search list. If it is a keyword, it 
must be one of ‘.first, ‘.newest, :newest-ask-compile, :newest-do- 

compile, or :call. If it is not a keyword, the list is treated as if it began 
with the keyword :first. 

:first [Keyword] 

■ A list in which this keyword appears denotes the pathname of the first 

existing file found by merging the remaining elements of the list with the 
supplied name. The search list ‘returns’ nil if no such file exists. The 

search list is processed sequentially from head to tail. Once an existing 
file is found, any remaining elements in the search list are not processed. 

:newest [Keyword] 

■ All of the remaining elements in the list in which this keyword appears 
are processed. From among all existing files denoted by these elements, 
the list returns the newest file, or nil if no files exist. 

:newest-ask-compile [Keyword] 

■ The second ( cadr ) element of the list containing this keyword must be 
a string or pathname. This second element is merged with the supplied 
name and the resulting pathname must name a fasl (compiled LISP) file. 
The remaining ( cddr ) elements of the list are then all merged with the sup- 
plied name and the first existing file denoted among them, which should 
be a source file, is selected. If the fasl file exists, and if it is newer than 
the first source file, the pathname of the fasl file will be returned. If no 
source file exists, the fasl file is returned. If no fasl file exists, or if the 
fasl file is older than the first source file, the user is asked whether the 
source file should be compiled to yield a new fasl file. If the response is 
affirmative, the file is compiled and the pathname of the fasl file is 
returned. Otherwise, the pathname of the newest source file is returned. 

If neither fasl file nor source file exists, nil is returned. 

:newest-do-compile [Keyword] 

■ A list containing this keyword is processed identically to a list contain- 
ing the ‘.newest-ask-compile keyword, except that the user is not asked 
whether a file should be compiled, the compilation is always performed if 
required and the pathname of the resulting fasl file is returned. 
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:call [Keyword] 

■ The second element of a list containing this keyword must be 
funcallable. This function is applied, once, to two arguments: the sup- 
plied name and the remaining elements ( cddr ) of the list. The function 
must return a pathname or a string or nil, and this value is returned by the 
search list. 


Suppose that you maintain a personal LISP ‘library’ in a subdirectory of your 
login directory, and that you wish to have the load function look for files in 
this subdirectory. Let us assume this subdirectory is named lisplib and that 
your login name is user. It would be reasonable, and you are a reasonable per- 
son, to search your library directory after searching your current working direc- 
tory but before searching the default library directory. Further, you’d like to 
automatically compile all files that are in your working or library directories. 
The following initialization of system :*load-search-path* in your initializa- 
tion file will accomplish this. We assume that your home directory pathname 
is /user/reasonable. 

(setq system:* load-search-list* 

’(:first 

(:newest-do-compile #.(make-pathname :type "fasl") 
#.(make-pathname :type "cl")) 

(:newest-do-compile 

#.(make-pathname directory Vuser/reasonable/lisplib" 

:type "fasl") 

#.(make-pathname directory "/user/reasonable/lisplib" 

:type "cl”) 

excl::*library-code-fasl-pathname* 

excl::*library-code-cl-pathname*)) 

If you start up LISP in the directory '/work and the Tek COMMON LISP 
library directory is /usr/ local/ lib/cl, the expression 

(load "too”) 

will result in the following pathnames being generated. 

'/work/foo.fasl 

'/work/foo.ci 

'/lisplib/foo.fasl 

'/lisplib/foo.cl 

/usr/lo cal/l i b/cl/f o o .f as I 

/usr/local/lib/cl/foo.cl 

If 7 work/foo.cl exists, '/work/foo.fasl will be compiled, if necessary, and 
loaded. If 7 work/foo.fasl exists but '/work/foo.cl does not, '/work/foo.fasl will 


3.3.2 

Example 
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Variables 


be loaded. If neither of these files exists, the next two files are examined. If 
~ llisplib/foo.cl exists, 1 lisp lib/ f oof as l will be compiled, if necessary, and 
loaded. If 7 lisp libi f oof as l exists but 'llisplib/foo.cl does not, 'llispliblfoofasl 
will be loaded. If neither of these files exists, the last two files are examined. 
If lusrllo cal! lib/ cl/foo fas l exists, it is loaded. If it does not exist, 
/usr/localllib/cllfoo.cl is loaded if it exists. If this last file does not exist, an 
error is signalled. 

=> If you change the value of *require-search-list* , you must include 
excl::*library-code-fasl-pathname* and excl::*library-code-cl-pathname* so 
that LISP will be able to find library files such as flavors. fas l and foreignfasl. 

The search list for the load function is bound to the symbol system:*load- 
search-list* . The default value for this symbol is 

(★default-pathname-defaults* 

#.(make-pathname :type "fasl") 

#.(make-pathname :type "cl") 

excl::*library-code-fasl-pathname* 

excl::*library-code-cl-pathname*) 

The load function looks for the file first by its exact name (without merging a 
file type, unless *default-pathname-defaults* has a non- nil file-type com- 
ponent) in the directory described by *default-pathname-defaults*. If it can- 
not find the file there, it looks in the same place for a file with a "fasl" file type, 
and then with a "cl" file type. Then it looks in the directory specified by 
excl::*library-code-fasl-pathname* and finally in the location specified by 
excl::*library-code-cl-pathname*. => The only difference between these two 
variables is the file type. If no file is found, then the search list returns nil and 
an error is signalled. 

The search list for the require function is bound to the symbol 
system:*require-search-list* and its default value is identical to that of 
system:*load-search-list* just described. 

syste m : * load-search-list* [Variable ] 

■ The search list examined by the load function. The default value of 
this search list is 

(★default-pathname-defaults* 

#.(make-pathname :type "fasl") 

#.(make-pathname -.type "cl") 

excl::*library-code-fasl-pathname* 

excl::*library-code-c!-pathname* 
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system:*require-search-list* [Variable] 

■ The search list examined by the require function. The default value of 
this search list is the same as the value of *load-search-list * . t 

excl::*library-code-fasl-pathname* [Variable] 

■ The value of this symbol is the pathname of the Tek COMMON LISP 
library directory’s fasl files. This symbol should be included in the search 
lists *load-search-list* and *require-search-list* . 

excl::*library-code-cl-pathname* [Variable] 

■ The value of this symbol is the pathname of the Tek COMMON LISP 
library directory’s source files. This symbol should be included in the 
search lists *load-search-list* and *require-search-list*. 


Tek COMMON LISP has the ability to ‘autoload’ files. A number of functions 
that are extensions to Standard COMMON LISP and which have a specialized 
audience are autoloaded. When the function is first referenced, the file in 
which the function is defined is loaded into LISP . 3 These autoload files are 
stored in a library directory on disk. The pathnames describing the location of 
fasl (fast-loadable, compiled) files and source files in this library directory are 
specified by the values of the variables excl::*library-code-fasl-pathname* and 
excl::*library-code-cl-pathname*. (The double colon indicates the symbol is 
not exported from the excl package.) 


3.4 

Autoloading 


exckuncompile function-name [Function] 

■ If the function function-name was compiled with the compile function 
(as opposed to having been in a file that was compiled with compile-file 
and subsequently loaded), then the function is ‘uncompiled,’ i.e. its func- 
tion definition is replaced by the original interpreted lambda form. 


3.5 

Miscellaneous 
functions 
and symbols 


exckbignump object 
exckfixnump object 
exckratiop object 
excksingle-floatp object 


[Function] 

[Function] 

[Function] 

[Function] 


■ These functions, like similar ones in Common Lisp return t if object is 
of the type specified, and nil otherwise. 


3 Examples of packages that are autoloaded are Flavors and the foreign-function interface. 
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excl:file-older-p file-1 file-2 [Function] 

■ If file-1 and file-2 both exist, and if file-1 is older than file-2, this func- 
tion returns t. Otherwise, it returns nil. 

excl:compile-file-if-needed filename &key ’.output-file :force - [Function] 

compile 

■ The file filename will be compiled if it is younger than the output file 
specified by the :output-file keyword argument, or if the value of the 
’.force-compile keyword argument is t. 

□ If ’.output-file is not given, the compiled pathname will be constructed 
by merging the extension with filename. 

□ This function, like compile-file, merges the value of ★source-file- 
type* to filename. See §2.4.1, File types, for a complete description. 

exckpp name [Macro] 

■ The definition of the function or macro name is ‘pretty printed’ to 
*standard-output* . Note that name is not evaluated. 

excl:if* test-form then then-form* {elseif else-test-form { then [Macro] 
else-then-form+ 1 thenret} }* [else else-form+] 

■ This form consists of a series of clauses introduced by the symbols 
then, elseif, else, and thenret. First the predicate test-form is evaluated. 
If it is non-nil, the then-forms are evaluated, and the value of the last such 
form is returned. If test-form evaluates to nil, any remaining clauses are 
processed. If no clauses remain, if* returns nil. When a thenret clause is 
encountered no further evaluation takes place, and the value of the most 
recently evaluated predicate is returned. When an elseif clause is encoun- 
tered, the predicate else-test-form is evaluated. If it is non-nil, the else- 
then-forms are evaluated, and the value of the last such form is returned; 
otherwise any remaining clauses are processed. If no clauses remain, if* 
returns nil. And lastly, when an else clause is encountered, the else-forms 
are evaluated, and the value of the last such form is returned. 
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lisp:intern 

lisp:find-symboI 

lisp:unintern 

lisprexport 

lisp:unexport 

lisp:import 

lisp:shadowing-import 

lisp:shadow 

lispruse-package 

lisp:unuse-package 


[Function] 

[Function] 

[Function] 

[Function] 

[Function] 

[Function] 

[Function] 

[Function] 

[Function] 

[Function] 


■ All of these standard COMMON LISP functions take a package as an 
optional argument. They have been extended to accept a symbol or a 
string instead, allowing the user in that way to specify a package with that 
name. If no package with the name exists, an error is signaled. 


*source-file-type* [Variable] 

■ This variable is merged with the file-name arguments to the function 
compile-file, the equivalent top-level command :cf, and the function 
compile-file-if-needed. It is fully described in §1.6.1. 

exclrgenerate-library-pathnames library-root-directory [Function] 

■ This function changes the pathname of the Tek COMMON LISP library 
directory. It updates the values of the symbols excl::*library-pathname * , 
excl::*library-code-pathname * , excl::*library-code-fasl-pathname* , 
excl::*library-code-cl-pathname* , and excl::*library-doc-pathname* . 
The argument library-root-directory must be a string. It cannot be a path- 


name. 
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4 Operating-system interface 


This chapter describes functions in Tek COMMON LISP that interact with the 
host operating system. These functions include those providing control and 
interaction with subprocesses, determination and change of the current working 
directory, and saving the state of a LISP session. 


system :os-wait [Function] 

■ If a process is started by the excl:run-shell-command with :wait 
being nil), then the process will remain in the system until either LISP 
exits or the process exits and LISP executes system :os-wait to inquire 
about the exit status. To prevent the system becoming clogged with 
processes, a program that spawns a number of processes with :wait set to 
nil must be sure to call system :os-wait for each spawned process. This 
function returns two values, the exit status of the process, and the process 
identification number. If there are no subprocesses running, then it will 
return immediately with the values nil, nil. 

excl:run-shell-command command &key :input : output [Function] 

terror-output :wait tif-input-does- 
not-exist -.if-output-exists tif-error- 

output-exists 

■ This function returns either one or three values, depending on the value 
of :wait. If :wait is t, the single value returned is the exit status of the 
spawned process. If :wait is nil, the three values returned are 

stream-a 

stream-b 

process-id 

where stream-a is a stream if either :input or ; output is '.stream and nil 
otherwise; and stream-b is a stream if terror-output is -.stream and nil 
otherwise. The process-id is the spawned process’s process identification 
number. Thus the user can communicate with the spawned process, 
including running any shell command, easily communicating the output to 
LISP. Writing to stream-a will send input to the spawned process if -.input 
is -.stream, and reading from stream-a will read the output of the process 
if -.output is tstream. 


4.1 

Subprocess 

functions 
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□ The values of :input, : output , and ’.error-output control what the pro- 
cess will use as standard input (file descriptor 0), standard output (file 
descriptor 1 ) and standard error (file descriptor 2). The values can be 

• nil — inherit standard input, output or error (respectively) from LISP. 
=s> This is UNIX standard input and output inherited from the LISP 
process and is unrelated to the LISP variables *standard-input* and 
★standard-output*. 

• A pathname (or string ) — open the file specifed by the pathname (or 
string) and use the stream; 

• A stream — use the stream (which must be able to do input/output in 
the right direction); 

• :stream — create create a stream and return it to the LISP program. 
Since waiting and having a stream open to a process can cause the 
process to hang, twait must be nil ; if ’.wait is t, an error will result. 

’.error-output has an additional allowed value: ’.output, which directs 
standard error to the same place as standard output. The default value in 
all cases is nil. 

□ ’.wait may be t or nil. If :wait is t, LISP will wait for the command to 
exit before resuming. If :wait is nil, LISP will start the process and then 
resume without waiting for it to finish. The default for ’.wait is t. 

□ The keywords :if-input-does-not-exist, :if-output-exists and tif- 
error-output-exists all are used for better control when ’.input, ’.output 
or terror-output are pathnames (or strings), LISP uses open to open a 
stream to the file identified by the pathname (or string) and the values of 
:if-input-does-not-exist, :if-output-exists and :if-error-output-exists 
are passed to the open function as the value of the tif-does-not-exist 
parameter (for ’.input ) or the :if-exists parameter (for ’.output or terror- 
output.) The permissable values for :if-does-not-exist are terror, 
’.create and nil and for :if-output-exists and tif-error-output-exists are 
terror, -.overwrite, ’.append, ’.supersede and nil. The default is terror 
in all cases. 

Here are examples of excl:run-shell-command. The first runs a simple shell 
command (path). The output goes to standard output (in this case the terminal.) 


<cl> (run-shell-coirtmand "path") 

/usr/tech/dm 

cox ttyp2 Sep 15 17:19 

dm ttyp8 Sep 16 14:01 (franz) 

0 

<cl> 


The next example reads the output into a stream, which can be manipulated by 
LISP. 
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<cl> (run-shell-command "csh" : input : stream 

: output : stream 
:wait nil) 

#<buffered terminal stream @ #x2c8c39> 
nil 


12059 

<cl> (setq foo *) 

#<buffered terminal stream @ #x2c8c39> 
<cl> (format foo "path“%'') 

;; ~% is a carriage return 

nil 

<cl> foo 

#<buffered terminal stream 0 #x2c8c39> 
<cl> (read foo) 

/usr/tech/dm 


excl -.shell &optional command [Function] 

■ If the command argument is not given, then an interactive shell is 
spawned. To get back to LISP, exit from the shell. If the command (a 
string) is given, then a shell is spawned and directed to execute that com- 
mand. 


exclxhdir pathname &key simple [Function] 

■ This function changes the current directory of the process to the direc- 
tory denoted by pathname (using the name and type information, not just 
the directory component of the pathname), and then sets the *default- 
pathname-defaults* to the directory just changed to. Argument simple 
defaults to nil, but if it is set to t, then *default-pathname-defaults* is 
unchanged (allowing, for example, files to be easily loaded from the origi- 
nal directory.) 

exclxurrent-directory [Function] 

■ Return a pathname with the directory component holding the current 
directory. 

system :command-line-argument n [Function] 

system xommand-line-arguments [Function] 

systemxommand-line-argument-count [Function] 

■ These functions provide information about the command line that 

invoked Tek COMMON LISP. They return, respectively, a string naming 

the nth argument (or the program name, if n is 0); a list of strings naming 
the program and the arguments; and a fixnum equal to the number of 


4.2 

Environment 

functions 
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4.3 

Image 

functions 


arguments. 

excl:username-to-home-directory name [Function] 

■ Return a pathname with the directory component holding the named 
user’s home directory, returns nil if the name is not recognized by the sys- 
tem. 

system :getenv string [Function] 

■ This function returns the value (a string ) of an environment variable 
(such as "TERM"). If the environment variable is not defined, nil is 
returned. 


exckdumplisp &key :name : restart-function :read-init-file [Function] 

■ Save an image of the currently executing COMMON LISP as an execut- 
able file. The name of the executable file will be savedcl unless the 
:name argument is provided. Unless the :read-init-file argument is given 
a value nil, when the saved image is executed, it will will search for and 
load the .clinit.cl file (see chapter 5, Top level, for a description of this 
file). Normally, the next step is for the top level to print a prompt and 
enter the read-eval-print loop. If however the :restart-function argument 
is given a non-nil value, then that value will be funcalled. Should the 
:restart-function return, the standard read-eval-print loop will be 
entered. 

exchexit &optional val [Function] 

■ Exit LISP and return exit status val to the operating system or shell. 
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5 Top level 


The user interacts with COMMON LISP in the top level. The top level facilitates 
the user’s interactions with LISP, allowing the user access the full power of the 
LISP environment In the top level, the user loads, debugs, and runs programs. 
The essence of the top level is a read-eval-print loop, which reads user input, 
evaluates it, and prints the result. Also in the top level are a set of commands 
that allow the user to do useful things, such as reevaluating a previously typed 
command, loading files, recovering from errors and debugging. 

The debugging tools in Tek COMMON LISP are integrated into the top 
level. They consist of a tracer, stepper, and inspector, a set of top-level com- 
mands that allow dynamic examination and manipulation of LISP data and the 
run-time evaluation stack, and mechanisms to single-step through expressions 
or function calls. 

The Tek COMMON LISP top level is modeless — all top-level commands 
are always accessible, regardless of what you are currently doing, be it tracing 
a function or simply entering expressions for evaluation. For example, while 
stepping through the expressions in a function, the user may want to examine 
the function’s parameters, abort stepping, display a traceback, ask for help on 
any top-level command, or exit COMMON LISP. There is one set of top-level 
commands that control all the functions of the top level. 


When COMMON Lisp is first invoked it looks for and loads one or more initiali- 
zation files. COMMON Lisp first searches the user’s home directory for a file 
called loading it if it is there; then COMMON LISP searches the current directory 
for a file of the same name, and if found, loads it too. The initialization file in 
the current directory overrides defaults set in the users home directory initiali- 
zation file. Any valid LISP expressions may be present in the initialization file, 
and it customizes the users LISP environment, by, for example, loading pro- 
grams or changing reader syntax. 

Top-level commands (prefixed by the top-level command character) can 
not be used from within the initialization file, or any other file. They may only 
be typed to the top level. 


Before reading input from the user, the top level issues a prompt. This prompt 
is initially the four character string "<cl> The user can change this prompt by 
changing the string value of the variable top-level:*prompt* . This string is 
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5.2.1 

Case 

sensitivity of 
input 


5.2.2 

Commands 

and 

expressions 


5.3 

Getting help 


given to the format function along with one argument, the current input 
expression number. For example, if the prompt string includes the two- 
character subsequence "~d”, the top level substitutes these characters with the 
decimal number that will . be assigned to the next input expression. See the 
documentation for format in Common Lisp for more information. 


A top-level command has the form 
:name arg 1 arg 2 ... argn 

The function that implements the command is passed n arguments, each 
corresponding to an argument read by the top level. The arguments may be 
read either the current case mode (for example :case-sensitive-lower or 
case-insensitive-lower ) or always in a case-sensitive mode. The only prede- 
fined top-level commands that always read their arguments in a case-sensitive 
mode are :ld and :cf, both of which take filenames as arguments. All other 
top-level commands read the arguments in the current case mode. When the 
user defines a top-level command (using the macro top-level :alias described in 
§5.12, Adding new top-level commands, below), the case sensitivity of input 
may be specified. Case sensitivity in general is discussed in §3.1, Reader case 
modes. 


The top level understands two sorts of input: top-level commands and LISP 
expressions. A top-level command is identified to COMMON LISP by prefixing 
it with a single character (initially the colon character). This can be changed 
by binding a different character object to the variable top-level:*command- 
char*. 

A newline typed to the top level is the null command, which is ignored, 
extra spaces and tabs are ignored, and typing an end-of-file has a special mean- 
ing, which is discussed below (see §5.5 and the description of the variable 
top-level:*exit-on-eof* in §5.11). In Tek COMMON LISP there is no top-level 
command that puts the user in debugging mode. Debugging commands are 
always available — the standard function calling sequence allows for the max- 
imum debugging information on the run-time stack. 

Some top-level commands may be abbreviated — refer to the : help com- 
mand for a list of the commands and valid abbreviations. 


:help [command-name] [Command] 

■ Without an argument, print a summary of the commands, mostly con- 
sisting of name, abbreviation, and valid arguments; if command-name is 
present, then print detailed documentation about this command. 
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As the user types commands and expressions to the top level, they are recorded 
on an entity called the history list. The value of top-level :*history* is the 
number of user inputs (commands or expressions) to remember, and is the 
maximum size the history list can grow. When the history list reaches its max- 
imum size, the oldest entries are thrown off as new ones are added. Note that 
only expressions and commands typed to the top level are added to the history 
list, but not input read from programs that are called from the top level. 

The following commands print and retrieve expressions from the history 
list: 

rhistory [.'reverse] [n] [Command] 

■ Print the last n, defaulting to 15, items on the history list, in reverse 
order if reverse is present. 

:[+|-]number [?] [ Command] 

“pattern [? | +] [Command] 

■ These two forms are the how previously typed expressions are 
reevaluated. The first form, cnumber, reevaluates the numberth typed 
expression, as reported by the history command. The second form, with 
an optional pattern, searches the history list for input matching pattern and 
reevaluates the matching expression as if it were typed to the top level, 
otherwise, the last expression typed is reevaluated. If + is given as an 
argument to the :: command form, then the search will be in the reverse 
sense, from the beginning of the history list forward, instead of from the 
end backward. If ? is an argument to either type of command, then the 
user will be asked to confirm the reevaluation of the command or expres- 
sion. For example: 


<cl> (setq top-level: *prompt* "<cl ~d> ") 

"<cl ~d> " 

<cl 3> :his 

1 (dribble "foo") 

2 (setq top-level : *prompt* "<cl ~d> ") 

3 : his 

<cl 4> (setq a 10) 

10 

<cl 5> (set 'b 'setq) 

setq 

<cl 6> : : setq 
(set 'b 'setq) 


5.4 

Command 

and 

expression 
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setq 

<cl 7> : : (setq 
(setq a 10) 

10 

<cl 8> :6 
(set 'b 'setq) 

setq 

<cl 9> :his 


1 

2 

3 

4 

5 

6 

7 

8 
9 

<cl 10> 


(dribble "foo") 

(setq top-level : *prompt* "<cl ~d> ") 
:his 

(setq a 10) 

(set 'b 'setq) 

(set 'b 'setq) 

(setq a 10) 

(set 'b 'setq) 

:his 


The main, or topmost, read-eval-print loop is labeled break level 0, and this is 
the level the user first enters. Each time an error occurs, a new read-eval-print 
loop, and thus a new break level, is entered. A new break level can only be 
entered in one of the following ways: (1) through the functions error, cerror, 
and break; (2) through the tracer, stepper, and inspector; (3) by external sig- 
nals, such as a keyboard interrupt; or (4) due to errors while reading, evaluat- 
ing, or printing user input. Cases (2) through (4) are really special cases of (1): 
all entrances to new read-eval-print loops are through the functions error, cer- 
ror and break. 

When a new break level is entered a message is printed, indicating the 
cause, and when break levels are exited, a reminder of the previous cause is 
printed. A break level is exited by using one of the :pop, :prt, :continue, or 
: reset commands. The function of the :pop command is also achieved by typ- 
ing an end-of-file character (usually "D on UNIX systems). 

Here are the commands to manipulate break levels: 

:reset [Command] 

■ This will reset the state of the top level, and return the user to break 
level 0. If errors have occurred, then all error conditions will be cleared, 
and a throw to the topmost level will be done. 
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xontinue [Command] 

■ If the current break level is continuable, then continue computation 
with side effects specified by the :error command. 

:pop [n] [Command] 

■ Pop up to the previous break level, or to the n th previous one, if n is 
given. 

□ => An end-of-file character typed in a break loop will have the same 
effect as :pop 1. 


:prt [ Command] 

■ Return to the previous break level, and retry the command that caused 
the error. The previous user input is printed before reevaluation as a rem- 
inder. 

:error [Command] 

■ Print the cause of entering the current break level. 


<cl> (setq foo bad) 

Error: Attempt to take the value of the unbound symbol bad. 

[1] <cl> (/ 1 0 ) 

Error: An attempt was made to divide by zero. 

[2] <cl> :pop 

Previous error: Attempt to take the value of the unbound symbol bad. 

[1] <cl> (setq bad :not-so-bad) 

: not-so-bad 
[1] <cl> :prt 

<cl> (setq foo bad) 

: not-so-bad 
<cl> foo 

: not-so-bad 

<cl> (cerror "just continue" "error!") 

Continuable Error: error! 

If continued with : continue, just continue 
[lc] <cl> :cont 

nil 
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5.6 

Stack 

commands 


The run-time stack is the entity where arguments to LISP functions are stored. 
When a function is called, the calling function evaluates and pushes the argu- 
ments to the called function onto the stack. The called function then references 
the stack when accessing its arguments. A stack frame is the area on the stack 
where the arguments to one function call reside. If too calls bar, which in 
turns calls yaf, then three stack frames are active when yaf is entered. The 
frame for the most recendy called function is on the top of the stack. The fol- 
lowing commands that access and display the stack operate on a single stack 
frame. After a frame is examined, it normally becomes the current stack 
frame, so further reference to the stack will, by default, operate on the previ- 
ously selected stack frame. When a break level is entered, the current frame 
pointer starts at the top of the stack. 

:zoom arguments* [Command] 

■ This command prints the evaluation stack. It uses the current stack 
frame as the center of attention, and prints some number of frames on 
either side of the current frame. The value of the variable top- 
level:*zoom-display* is the total number of frames to display, and an 
equal number of frames are printed above and below the current stack 
frame, if possible. The arguments to the :zoom command control the type 
and quantity of the displayed stack. After a :zoom, the special variable * 
contains the LISP expression representing the current frame. 

□ Only one of the following three argument options may be specified. 
(The following output control options stick, meaning once you use one, 
the next :zoom will use the same output style.) 


'.brief [Keyword] 

□ Print the function names of stack frames only. 

'.moderate [Keyword] 

□ Print function names, and actual parameters (the values passed on 
the stack). The output of this form is LlSP-like in appearance. 

; verbose [ Keyword ] 

□ Print function names, formal (the names of the parameters in the 
function definition) and actual parameters. 

□ One of the following two options may also be specified: 
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:top [Keyword] 

□ Move the current stack frame pointer to the top of the stack before 
printing. Newer stack frames are toward the top of the stack. 

: bottom [Keyword] 

□ Move the current stack frame pointer to the bottom of the stack 
before printing. Older stack frames are toward the bottom of the 
stack. 


n [Option] 

□ Print n frames, where n is an integer, instead of using the value of 
top-level:*zoom-display * , initially 8. 

:up [n] [ Command] 

:dn [n] [ Command] 

■ Move up or down the stack by n frames, or 1 if no argument is sup- 
plied. The special variable top-level:* auto-zoom * , which defaults to t, 
controls whether a :zoom is done after moving the stack pointer. 

:find func options* [Command] 

■ Find the frame where function func is being called. The default direc- 
tion to search the stack is down, or towards older stack frames. The 
current frame pointer is set to point to the matching stack frame, and the 
LISP expression corresponding to the match is bound to the variable *. 
The options to :find are: 


:up [Keyword] 

:dn [Keyword] 

□ Find func going up (toward newer stack frames) or down (toward 
older stack frames) the stack. 

‘.skip n [Keyword] 

□ Skip n matching occurrences of func before setting the current 
frame pointer. 


:current 


[Command] 


■ Print the current stack frame, as a LISP expression. 
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rlocal name [ Command ] 

■ This prints the value of the local (or lexical) variable name. When a 
variable is bound in a function by using let, for example, the scope of this 
variable is visible only inside this function. For this reason, the :local 
command is needed to examine the environments of functions on the 
stack. 

The following special variables are used by the :zoom command. 

top-level : *zoom-displ ay* [Variable] 

■ The value of this variable is the number of stack frames displayed by 
the :zoom command. 

top-level:*zoom-print-level* [Variable] 

top-level : *zoom-print-le ngth * [ Variable ] 

■ During the printing of stack frames, *print-level* and *print-length* 
are bound to these, respectively. See page 372 of Common Lisp for an 
explanation of *print-level* and *print-length*. 


<cl> (defun func (x) (car x) ) 

func 

<cl> (func 10) 

Error: Attempt to take the car of 10 which is not a cons. 

[1] <cl> :zo 
Evaluation stack: 

-> (lisp : : read-eval-print-loop nil ...) 

(error) 

(car 10) 

(block func . . . ) 

(f uncall (lambda # ...) ...) 

(eval (func 10) ) 

(lisp :: read-eval-print-loop nil ...) 

( start-reborn-lisp) 

[1] <cl> :find block 

Evaluation stack: 

(lisp :: read-eval-print-loop nil ...) 

(error) 

(car 10) 

-> (block func . . . ) 

(f uncall (lambda # ...) ...) 

(eval (func 10) ) 

(lisp :: read-eval-print-loop nil ...) 
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(start-reborn-lisp) 

[1] <cl> * 

(block func (car x) ) 

[1] <cl> : local x 
10 

[1] <cl> terror 

current error: Attempt to take the car of 10 which is not 

[1] <cl> : current 
(block func (car x) ) 

[1] <cl> :pop 
<cl> (compile 'func) 

#<Function func @ #xll48cl> 

<cl> (func 10) 

Error: Attempt to take the car of 10 which is not a cons. 

;; notice that there is less information on the stack 
;; when the function 'func' is compiled... 

[1] <cl> :zo 
Evaluation stack: 

-> (lisp : : read-eval-print-loop nil ...) 

(error) 

(func 10) 

(eval (func 10) ) 

(lisp :: read-eval-print-loop nil ...) 

(start-reborn-lisp) 

[1] <cl> 


:aliases [ Command] 

■ This command prints all user-defined aliases in tabular format, with the 
documentation string, if there is one. 

□ See §5.12, Adding new top-level commands, below for a further 
discussion of aliases. 

:cf file* [Command] 

■ The one or more arguments are interpreted as file names, which should 
represent the names of Tek COMMON LISP source files. The list of source 
files are compiled, resulting in files with the same name, but with the file 
type of "fast". For example, :cf foo would compile foo.cl into foo.fasl, 
which is acceptable to the function load. The files are compiled in the 
order they appear in the argument list. For convenience, as the previous 
example illustrates, the file names may be given without the file type, 


a cons . 


5.7 

Miscellaneous 

commands 
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5.8 

The tracer 


which then default to "d”. The user may change the default source-file 
type. This is discussed in §2.4.1, File types. Compiling files and func- 
tions is discussed in §1.6, How to compile functions. Pathnames are 
discussed in §2.3 of this User Guide and in Chapter 23 of Common Lisp. 

□ The arguments to this command are read in case-sensitive mode. 

□ If no arguments are given to :cf, then the arguments to the last call to 
:cf are used again. 

:exit [val] [ Command] 

■ Exit LISP and return exit status val to the operating system or shell. 

:ld file* [Command] 

■ The arguments to :ld are loaded into LISP by the load function. 

□ The arguments to this command are read in case-sensitive mode. 

□ With no arguments, the last files given to the :ld command are loaded 
again. 

The tracer provides a way to track or trace when functions are called. For 
example, when tracing a function, a message is printed upon entering and exit- 
ing the function. 

The tracer is invoked at the top level using rtrace and turned off using 
:untrace. The tracer can also be invoked and exited using the functions trace 
and untrace, which have the same argument syntax as their top-level com- 
mand counterparts (see the example below). 

The output from trace is designed to be readable — a function being traced 
may be called many times, and the entrance and exit from each instance should 
be obvious, by the numbers at the beginning of the lines and the indentation of 
the lines printed by the traced function. The trace function and all the special 
variables are exported from exd package (see Chapter 9). 

:trace function-or-option-list* [Command] 

■ With no arguments, all the functions currently being traced are printed, 
otherwise the arguments to :trace are function names (symbols) or option 
lists. An option list starts with a function name, and the rest of the list are 
options for tracing that particular function, and do not affect the tracing of 
any other function. The options come in pairs, the first element of the pair 
being the option name (i.e., a keyword), and the second part being the 
option value. Missing options default to nil. 

□ The following are valid options to :trace: 
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condition expr [Keyword] 

■ Trace this function if expr evaluates to non-nil. 

:break-before val [Keyword] 

:break-after val [Keyword] 

:break-all val [Keyword] 

■ The expression val is evaluated just before entering a function, 
just after exiting a function, and at both times, respectively. If val is 
t, then enter a new break level is entered. Otherwise, execution con- 
tinues. 


:inside tunc [Keyword] 

■ Trace this function if we are currently inside the evaluation of the 
function tunc, tunc may also be a list of functions. For example, 
(trace (deeper :inside deep)) would trace the function deeper only 
when called from within a call to deep. 

: print-before expr [Keyword] 

:print-after expr [Keyword] 

:print-all expr [Keyword] 

■ expr should either be a single object or a list of object which are 
evaluated, and the results printed before entering or after leaving the 
function, or both, in the case of :print-all. 

:untrace [function-list] [ Command] 

■ With no arguments, stop tracing all functions currently being traced, 

otherwise the arguments are assumed to be the names of currently traced 
functions which are to be untraced. :untrace also has a function counter- 
part, called untrace. 

The following are special variables understood by the tracer. 

excl:*trace-output* [Variable] 

■ The stream where rtrace sends output, which is normally *terminal- 

io*. 


excl:*trace-print-level* [Variable] 

excl : *trace-pri nt-le ng th * [Variable ] 


■ During the printing of trace forms, *print-level* and *print-length* are 
bound to these, respectively. See page 372 of Common Lisp for an expla- 
nation of *print-level* and *print-length* . 
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<cl> (defun fact (n) 

(cond ((= n 1) 1) 

(t (* n (fact (1- n)))))) 

fact 

<cl> (fact 5) 

120 

<cl> :tra fact 
fact 

<cl> (fact 5) 

0: (fact 5) 

1: (fact 4) 

2: (fact 3) 

3: (fact 2) 

4: (fact 1) 

4 : returned 1 
3 : returned 2 
2 : returned 6 
1: returned 24 
0: returned 120 
120 

<cl> (defun deep (x) (deeper (list x) ) ) 

deep 

<cl> (defun deeper (x) (format t "~4~s~%" x) ) 

deeper 

<cl> (deep 10) 

( 10 ) 

nil 

<cl> :tr (deeper : inside deep) 

deeper 

<cl> (deeper 10) 

10 

nil 

<cl> (deep 10) 

0 : (deeper (10) ) 

( 10 ) 

0 : returned nil 
nil 

<cl> :tr (deeper : break -be fore t) 
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deeper 

<cl> (deep 10) 

0: (deeper (10)) 

Break: trace entry 
[lc] <cl> :zo 
Evaluation stack: 

-> (lisp : : read-eval-print-loop t ...) 
(break "trace entry") 

(lisp: : trace-call (lambda # ...) ...) 

(let (# #) . . . ) 

(funcall (lambda # ...) ...) 

(block deep . . . ) 

(funcall (lambda # ...) ...) 

(eval (deep 10) ) 

[lc] <cl> :cont 

(10) 

0 : returned nil 
nil 
<cl> 


The stepper allows the user to watch and control the evaluation of LISP expres- 
sions, either inside certain functions or over certain expressions. When step- 
ping is turned on, evaluation of all expressions is done in single-step mode — 
after evaluating one form, a step read-eval-print loop is entered, from which the 
user may continue or abort. 

As with the :trace command, :step is a top-level command and step is a 
function. 

With no arguments or an argument of nil , step turns off stepping. With 
an argument of t, stepping is turned on globally, otherwise the arguments are 
checked to be functions, and stepping is done only when inside one of the func- 
tions given to step. 

Once stepping is turned on, the top level recognizes three more com- 
mands: :scont, :sover, and carriage return (which is a synonym for :scont 1). 
Also, the top-level prompt for step read-eval-print loops is prefixed with [step], 
as a reminder that the above step commands are available. 


5.9 

The stepper 


:step [t | nil | function-list] [Command] 

■ With no arguments or an argument of nil, stepping is disabled, with an 
argument of t, stepping is enabled globally, otherwise the arguments are 
assumed to be a list of functions wherein stepping should occur. Any 
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non-functions supplied to :step will be flagged as invalid arguments, and 
an error will not occur. 

:scont [n] [Command] 

■ Continue stepping, for n expressions, and evaluate the last expression 
printed by the stepper. After evaluating the last printed expression, the 
next expression to be evaluated is printed. If there are no more expres- 
sions stepping is turned off. When stepping is enabled, a carriage return 
(or new-line) character is equivalent to :scont 1 , allowing the user to step 
quickly with minimum keystrokes. 

:sover [ Command] 

■ Evaluate the current expression in normal, non-stepping mode. 

The following special variables, all exported from excl package, control output 
from the stepper: 

*step-print-level* [Variable] 

★step-print-length* [Variable] 

■ During the printing of forms to be evaluated, *print-level* and *print- 
length* are bound to the value of these variables, respectively. See page 
372 of Common Lisp for an explanation of *print-level* and *print- 

length*. 


5.10 

The 

inspector 


The inspector allows the user to look at the internal structure of Tek COMMON 
LISP objects. The commands that control inspecting objects are part of the Tek 
COMMON Lisp top level command structure. The a'nspect command simply 
invokes a recursive top-level command interpreter. Thus all the normal Tek 
COMMON lisp commands are available while inspecting objects. The inspect 
commands are all variations of the top-level command :inspect which may be 
abbreviated :i. The inspector maintains a stack of objects whose components 
are being inspected. The top object on that stack is called the current object, 
and can be displayed at any time. When the current object has components, 
these are displayed with prefixes of the form index name where index is a 
numeric index associated with the component and name is a symbolic name for 
the component. The user can select a component of the current object by name 
or index, and add it to the stack, making the selected component the new 
current object. The user can also pop the current object off the stack, making 
its parent object the current object again. In this way the user can explore the 
structure of compond objects to any depth. All the inspect commands except 
tinspect q described below, return the current object so that it gets bound to * 
(see above for a description of *). 
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inspect object [Function] 

■ Perform special bindings of the inspector’s state variables, including 
the inspect stack. Then initialize the (new) inspect stack to contain only 
object display object’s structure, and then invoke a top-level read-eval- 
print loop. The read-eval-print loop is terminated when the user enters the 
command inspect q and inspect then returns object. 

linspect ? [Command] 

■ This command prints a message describing the inspector commands. 

:inspect [Command] 

■ When entered with no arguments, :inspect redisplays the structure of 
the current object. 

:inspect * [Command] 

■ This command initializes the inspect stack to hold only the value of 
that is, the first result from the last top-level evaluation. This object 
becomes the inspector’s current object and its structure is displayed, 
(inspect *) is like an inspect * invoked within a recursive read-eval- 
print loop that sets up its own inspect stack. 

inspect index [Command] 

■ This command, where index is an integer, selects the indexth com- 

ponent of the current object. The selection is made according to the com- 
ponent indexes displayed by inspect, which may not be the same as the 
element numbers used by other Tek COMMON LISP functions. Some 

object components cannot be selected. Elements of a specialized vector, 
for example, are displayed as components but cannot be made the current 
object. Attempting to select such a component will elicit an explanatory 
message but will not signal an error. 

:inspect name [Command] 

■ This command, where name is a symbol that is not one of the special 

inspector command symbols (such as *, q, and set), selects the named 
component of the current object. The component names are those 
displayed by inspect They are compared using string-equal, so case and 
package are not significant. If a component’s name is shadowed by 
another component’s name or by one of the inspector command symbols, 
then the numeric index can be used to select the shadowed component. 
The inspector considers the tail of a dotted list to be a component with no 
numeric index but with the component name tail. The tail of a proper list 
can also be designated by name, even though no tail component is 
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displayed for such an object. In addition, the component names car, cdr, 
caar, cadr, cdar, cddr, caaar, cdddr, caaaar, ..., cddddr, are recognized 
for selecting the named components of list structures. 

□ As with selection by index, attempting to select an unselectable com- 
ponent by name results in an explanation but no error. 

inspect - [Command] 

■ Remove the current object from the inspect stack and display the new 
current object. The new current object will be the parent of the old 
current object. If the inspect stack is empty or has only one entry, then the 
current object is not changed and an explanatory message is displayed. 

inspect q [Command] 

■ This command clears the inspect stack, so that there is no current 
object. If there is an active invocation of inspect, then the inner-most 
invocation returns to its caller. (This is important if you are looking at a 
large object which you want to be garbage collected. No object on the 
inspect stack will be garbage collected.) 

inspect set index form [Command] 

■ The form is evaluated for a single value. If the current object has a 
settable component indexed by index, then the value of form is stored as 
that component. If there is no current object, or it has no settable com- 
ponent indexed by index, or if the type of that component does not admit 
assignment of form’s value, then an explanatory message is displayed and 
the component is not changed. Many components that are not selectable 
are settable. Elements of specialized vectors, for example, are settable. 

inspect set name form [Command] 

■ This sets a named component of the current object. It is identical to the 
indexed inspect command except for the method of selection. See 

inspect name. 

inspect print max [Command] 

■ The inspector limits the number of components that it displays. The 
maximum number defaults to 12, but can be changed by using the 
inspect print command, max must be a positive integer. 

inspect skip n [Command] 

■ The inspector redisplays the current object, omitting the first n com- 
ponents. This allows the display of any section of a large structure or 
array without filling the screen with unwanted information. 
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inspect tree [Command] 

■ This command displays the elements of the inspect stack so the user 
can see the geneology of the current object relative to the object specified 
by inspect * or (inspect x). 


<cl> (inspect '#(car x 12 # #*1000 (1/2 0.5 0.5d0))> 

A simple T vector (6) 0 #x2c5749 

0- > The symbol CAR 

1- > The symbol X 

2- > The fixnum 12. [#x00000060] 

3- > The character # [#x000003Q8] 

4- > A simple-bit-vector (4) #*1000 

5- > A proper list with 3 elements 
[1] <cl> :i 0 

The symbol CAR 0 #xlb4622 

which is an EXTERNAL symbol in the LISP package 

0 value-> . .unbound. . 

1 package-> The LISP package 

2 function-> #<Function CAR 0 #x229c29> 

3 name-> A simple-string (3) "CAR" 

4 plist-> A proper list with 6 elements 

5 hash-> Bit field: #x013c 

6 flags-> Bit field: #x0000 
[1] <cl> :i 4 

A proper list 0 #xlb463c with 6 elements 

0- > The symbol COMPILER: : .ARGS . 

1- > A dotted list with 1 cells 

2- > The symbol M68K: : . S-BIFS . 

3- > The symbol M68K::S-CAR 

4- > The symbol EXCL : : SETF-INVERSE 

5- > The symbol EXCL : : . INV-CAR 
[1] <cl> :i tree 

In first recursive call to inspect. 

The current object is: 

A proper list with 6 elements, which is the 
plist component of 

The symbol CAR, which is component number 0 of 
A simple T vector (6), which was 
selected by " (inspect . . . ) " 

[1] <cl> :i - 

The symbol CAR 0 #xlb4622 

which is an EXTERNAL symbol in the LISP package 

0 value-> . .unbound. . 

1 package-> The LISP package 

2 function-> #<Function CAR 0 #x229c29> 

3 name-> A simple-string (3) "CAR" 

4 plist-> A proper list with 6 elements 

5 hash-> Bit field: #x013c 
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6 flags-> Bit field: #x0000 
[1] <cl> :i 5 

Cannot select the element indexed by 5 
[1] <cl> :i - 

A simple T vector (6) 0 #x2c5749 

0- > The symbol CAR 

1- > The symbol X 

2- > The fixnum 12. [#x00000060] 

3- > The character # [#x00000308] 

4- > A simple-bit-vector (4) #*1000 

5- > A proper list with 3 elements 
[1] <cl> :i 1 

The symbol X @ #x2c53da 

which is an INTERNAL symbol in the USER package 

0 value-> . .unbound. . 

1 package-> The USER package 

2 function-> #<Function NIL 8 #xla29a9> 

3 name-> A simple-string (1) "X" 

4 plist-> The symbol NIL 

5 hash-> Bit field: #x0078 

6 flags-> Bit field: #x0000 
[1] <cl> :i set value 0 

The symbol X 0 #x2c53da 

which is an INTERNAL symbol in the USER package 

0 value-> The fixnum 0. [#x00000000] 

1 package-> The USER package 

2 function-> #<Function NIL 0 #xla29a9> 

3 name-> A simple-string (1) "X" 

4 plist-> The symbol NIL 

5 hash-> Bit field: #x0078 

6 flags-> Bit field: #x0000 
[1] <cl> :i - 

A simple T vector (6) 0 #x2c5749 

0- > The symbol CAR 

1- > The symbol X 

2- > The fixnum 12. [#x00000060] 

3- > The character # [#x00000308] 

4- > A simple-bit-vector (4) #*1000 

5- > A proper list with 3 elements 
[1] <cl> :i 5 

A proper list 0 #x2c564c with 3 elements 

0- > A RATIO object 1/2 

1- > A single-float 0.5 [#x3f 000000] 

2- > A double-float 0.5d0 [#x3fe00000 00000000] 
[1] <cl> :i set tail (cdr *) 

A closed list 0 #x2c564c with 1-element header 
and 2-element cycle 

0- > A RATIO object 1/2 

1- > A single-float 0.5 [#x3f000000] 
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2-> A double-float 0.5d0 [#x3fe00000 00000000] 

3 == 1 

[1] <cl> :i tail 

Object has no selectable component named TAIL 
[1] <cl> :i q 

# (CAR X 12 #\a #*1000 (1/2 0.5 0 . 5d0 0.5 0 . 5d0 0.5 0 . 5d0 0.5 
<cl> 


The following variables are maintained or used by the top level. 

top-level : * auto-zo o m * [Variable ] 

■ If nil, then the top-level commands :dn and :up will not cause the stack 
to be printed. The default is t, which causes a :zoom, printing the frames, 
to happen after moving to the new frame. 

top-level:*command-char* [ Variable ] 

■ The character recognized as the prefix for top-level commands. The 
value of this variable must be a character object, and is initially the LISP 
character object u#\;. 

top-level:*history* [ Variable ] 

■ The number of commands which are remembered by the history 
mechanism, defaulting to 15. 

top-level:*prompt* [Variable] 

■ The value of this variable is printed by the top-level as a prompt for 
user input; it must be a LISP string. For break levels greater than 0, this 
prompt will be augmented with the break level number. In continuable 
break levels a V will be present next to the break level indicator. 

top-level :*exit-on-eof* [Variable] 

■ If bound to a non- nil value and the current break level is 0, then typing 
an end-of-file to the top-level will exit LISP, without asking for confirma- 
tion. The method of exit is taken via the function exit. The default value 
is nil. 

top-level:*ld-options* [ Variable ] 

■ Since the :ld command now simply calls the COMMON LISP function 
load, passing all the arguments to :ld unchanged to load, this variable is 
now obsolete and has no effect. Options for load are optained by the ,tf B 
search-list facility described in §3.3. 


0 . 5d0 0.5 
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Top-level 

variables 
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top-level:*file-ignore-case* 


[Variable] 


■ Since in this release, by default, :ld and :cf read arguments in a case- 
sensitive fashion, this variable, which controlled case-sensitivity of those 
is now obsolete. It has no effect in this release. Users can control the case 
sensitivity of top-level commands when they are defined using the top- 
level :alias command described in §5.12. 


top-leve!:*read* 

top-level:*eval* 

top-level:*print* 


[Variable] 

[Variable] 

[Variable] 


■ The values of these variables, if bound to valid functions (acceptable to 
the function funcall), will be funcalled to read user input, evaluate the 
result the top-level:*read*, and print the result of top-level :*eval*, 
respectively. Great care should be taken before setting one of these vari- 
ables, since binding these to something other than a function will result in 
a recursive error (since after an error, another read-eval-print loop is 
called). 


top-level:*print-level* 
top-level :*print-length* 


[Variable] 

[Variable] 


■ lisp:*print-level* and lisp:*print-length* are bound to these, respec- 
tively, during the application of the top-level :*print* function on the result 
of the top-level:*eval* function. See page 372 of Common Lisp for an 
explanation of lisp:*print-level* and lisp:*print-length * . 


top-leve!:*reset-hook* 


[Variable] 


■ If non-nil, and bound to a valid function (something acceptable to fun- 
call), then this function is called after executing the ‘.reset command. 

Note: The following variables are required by Common Lisp. 


+ [Variable] 

++ [Variable] 

+++ [Variable] 

■ While an expression or form is being evaluated by top-level:*eval*, 
the variable + is bound to the previous form read by top-level:*read* . 
The variable ++ holds the previous value of +, or the form read two reads 
ago, and +++ holds the previous value of ++. 
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[Variable] 

■ While a form is being evaluated by top-level:*eval*, the variable - is 
bound to the form itself, or the value which will be given to + after top- 
level:*eval* returns. 


* 

** 

*** 

■ While a form is being evaluated by top-level:*eval* , the variable * is 
bound to the last value returned from top-level:*eval* , or the value pro- 
duced by evaluating the form in +. If more than one value is returned, all 
but the first are discarded, and if zero values were returned, then * is 
bound to nil. The variable ** holds the previous value of *, or the result 
of the second previous top-level:*eval*, and *** holds the previous 
value of **. 

□ If the evaluation of + produces an error, then *, **, and *** are left 
untouched; they are updated before top-level:*print* is called. 


[Variable] 

[Variable] 

[Variable] 


/ [Variable] 

II [Variable] 

III [Variable] 

■ While a form is being evaluated by top-level:*eval*, the variable / is 
bound to the list of results from the last top-level:*eval*, or the list of all 
values produced by evaluating the form in +. The value of * should be 
the same as the car of the value of /. The variable // holds the previous 
value of /, or the list of results from second previous top-level:*eval*, and 
/// holds the previous value of //. Therefore, the car of // should be the 
same as ** , and the car of /// the same as ***. 

□ If the evaluation of + produces an error, then /, //, and /// are left 
untouched; they are updated before top-level:*print* is called. 


The top-level command set is extensible — the user may add new commands to 
the list of known commands. This allows the user to further customize the 
top-level environment. 

A top-level alias is a user defined top-level command, which is invoked 
the same as built-in top-level commands. The difference between built-in com- 
mands and aliases, is aliases can be removed, one at a time or all at once. 


5.12 
Adding new 
top-level 
commands 


top-level:alias {name | (name [option ...])} arglist body [Macro] 

■ This is how top-level aliases are defined. The form of top-level :alias 
is similar to defun, and body can be anything acceptable as the body of a 
lambda expression, name is the name of the top-level alias, which must 
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be a string. If the (name [option ...]) form is used, the options are (either 
or both may be specified) tease-sensitive and abbr-index. If the tease- 
sensitive option is chosen the arguments will be read in case-sensitive 
mode without regard to the current reader mode. This option is appropri- 
ate when the argument is a filename. Case-sensitivity is fully describe in 
§3.1. abbr-index must be an integer which is the index into the string 
name which defines the shortest possible abbreviation. Note that string 
indexing is zero-based. For example, ("load" 1 ) would specify that lo and 
loa are valid abbreviations for load, while ("load" 0) would specify / as 
well, arglist is the list of formal parameters to the alias function, and has 
the same form as the formal list to a lambda expression. 

top-level:remove-alias &rest names [Function] 

■ This will remove the alias commands known by names, or all user 
defined aliases if the argument is tail. Built-in top-level commands may 
not be removed with this function. If abbreviations were specified for 
names, then all abbreviations are also removed from the command set. 

top-level:do-command name &rest arguments [Function] 

■ This function allows the execution of top-level commands from pro- 
grams. It hides the method of dispatch for top-level commands, and 
should be the sole means of accessing top-level commands outside typing 
them to the top-level read-eval-print loop. 

□ name must be a string and the name of a top-level command, otherwise 
an error occurs. 


<cl> (top-level : alias "ff" (firest args) 

"my alias for the : find command" 

(apply #' top-level : do-command "find" args)) 

<cl> (defun test (x) (break "testing...")) 

test 

<cl> (test nil) 

Break: testing... 

[lc] <cl> :zo 
Evaluation stack: 

-> (lisp : : read-eval-print-loop t ...) 

(break "testing...") 

(block test . . . ) 

(f uncall (lambda # ...) ...) 

(eval (test nil) ) 

(lisp :: read-eval-print-loop nil ...) 
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(start-reborn-lisp) 

[lc] <cl> :ff block 
Evaluation stack: 

(lisp: : read-eval-print-loop t . . . ) 
(break "testing. . . 

-> (block test . . . ) 

(funcall (lambda # . ..) ...) 

(eval (test nil) ) 

(lisp :: read-eval-print-loop nil ...) 
( start-reborn-lisp) 


As described earlier in this chapter, if a file exists in the user’s home directory 
(or in his working directory), it is loaded when LISP starts up. This provides a 
method for customizing your LISP environment. The sample initialization file 
below sets several top-level variables, defines “X as an exit character, and 
defines a new top-level command :shell (which can be abbreviated down to 
:sh) that executes a shell command. 


5.13 
A sample 
initialization 
file 


/ / 

; ; common lisp initialization file 

r r 


(format *terminal-io* Loading home init file.") 

(setq 

top-level : *prompt* "<cl ~d> " 
top-level : ^history* 50 
top-level : *print-level* 20 
top-level : *print-length* 20 
top-level : *zoom-print-level* 3 
top-level : *zoom-print-length* 3 
top-level : *zoom-display* 7 
top-level : *exit-on-eof * t 
top-level : *command-char* #\? 
top-level : *auto-zoom* nil) 

; ; exit when a control-X is typed to the top level 
(defun exit-char-mac (stream char) (exit 0)) 

; ; the ~X in the next expression is the single 
; ; character control-X 

(set-macro-character #\~X #' exit-char-mac) 

(top-level : alias ("shell" 1 : case-sensitive) (Srest args) 
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" ' : sh args' will execute the shell command in 'args'" 
(let ( (cmd 

(apply #' concatenate 'simple-string 
(mapcar #' (lambda (x) 

(concatenate 'simple-string 
(write-to-string x) " " ) ) 
args) ) ) ) 

(prinl (shell cmd) ) ) ) 


0 - 01 - 02(2 



6 Flavors 


The object-oriented programming style used in the Smalltalk and Actor 
families of languages is available in Tek COMMON LISP. Its purpose is to per- 
form generic operations on objects. Part of its implementation is simply a con- 
vention in procedure-calling style; part is a powerful language feature, called 
Flavors, for defining abstract objects. This chapter explains the principles of 
object-oriented programming and message passing, and the use of Flavors in 
implementing these in Tek COMMON LISP. It assumes no prior knowledge of 
any other languages. 

The implementation of Flavors distributed by Franz Incorporated with Tek 
COMMON LISP is new, proprietary code which employs special interpreter and 
compiler hooks for very efficient execution. The code shares some com- 
ponents with the Franz Inc. native implementation of Flavors distributed with 
FRANZ Lisp. Except where the underlying LISP dialects require fundamental 
differences (for example, in variable scoping) the two Flavors systems are 
functionally identical. The Tek COMMON LISP implementation of Flavors is 
also quite similar to that in Symbolics LISP, 1 although a few details and exten- 
sions differ. Most code should port easily between the two. Unless otherwise 
indicated, all the symbols defined in this chapter are exported from the flavors 
package. Users must either use the qualifier flavors: or execute 

(use-package ’flavors) 
before using flavors code. 

The text of this chapter is a heavily-edited version of Chapter 20 from the 
MIT LISP Machine Manual, as made available through MIT’s Project Athena. 
It has been subsequently edited by the staff of Franz Inc. for inclusion in the 
Tek COMMON LISP manual. 


When writing a program, it is often convenient to model what the program 
does in terms of objects, conceptual entities that can be likened to real-world 
things. Choosing what objects to provide in a program is very important to the 
proper organization of the program. In an object-oriented design, specifying 
what objects exist is the first task in designing the system. In a text editor, the 
objects might be pieces of text, pointers into text, and display windows. In an 
electrical design system, the objects might be resistors, capacitors, transistors, 

1 That is, ‘Genera 6’ FLavors. The newest Symbolics ‘Genera 7’ Flavors differs substantially. 
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wires, and display windows. After specifying what objects there are, the next 
task of the design is to figure out what operations can be performed on each 
object. In the text editor example, operations on pieces of text might include 
inserting text and deleting text; operations on pointers into text might include 
moving forward and backward; and operations on display windows might 
include redisplaying the window and changing which piece of text the window 
is associated with. 

In this model, we think of the program as being built around a set of 
objects, each of which has a set of operations that can be performed on it. 
More rigorously, the program defines several types of object (the editor above 
has three types), and it can create many instances of each type (that is, there 
can be many pieces of text, many pointers into text, and many windows). The 
program defines a set of types of object and, for each type, a set of operations 
that can be performed on any object of the type. 

The new type abstractions may exist only in the programmer’s mind. The 
mapping into a concrete representation may be done without the aid of any pro- 
gramming features. For example, it is possible to think of an atom’s property 
list as an implementation of an abstract data type on which certain operations 
are defined, implemented in terms of the LISP get function. There are other 
property lists (association lists of pairs) which are, however, not stored in the 
global structure of an atom, such as are implemented in terms of the COMMON 
LISP getf function. Such a property list is just a list with an even number of 
items. This type can be instantiated with any function that creates a list; for 
example, the form (list ’a 23) creates a new property list with a single key/value 
pair. The fact that property lists are really implemented as lists, indistinguish- 
able from any other lists, does not invalidate this point of view. However, such 
conceptual data types cannot be distinguished automatically by the system; one 
cannot ask: is this object a disembodied property list, as opposed to an ordi- 
nary list? 

Use of defstruct is another mechanism for creating new data types. This 
is reviewed in the next section, where a data type for ship is used as an exam- 
ple. defstruct automatically defines some operations on the objects: the opera- 
tions to access its elements. We could define other functions that did useful 
computation with ships, such as computing their speed, angle of travel, 
momentum, or velocity, stopping them, moving them elsewhere, and so on. 

In both cases, we represent our conceptual object by one LISP object. The 
LISP object we use for the representation has structure and refers to other LISP 
objects. In the case of a property list, the LISP object is a list of pairs; in the 
ship case, the LISP object is an array or vector whose details are taken care of 
by defstruct. In both cases, we can say that the object keeps track of an inter- 
nal state, which can be examined and altered by the operations available for 
that type of object, getf examines the state of a property list, and setf of getf 
alters it; ship-x-position examines the state of a ship, and (setf (ship-x-position 
ship) 5.0) alters it. 
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This is the essence of object-oriented programming. A conceptual object 
is modeled by a single LISP object, which bundles up some state information. 
For every type of object, there is a set of operations that can be performed to 
examine or alter the state of the object. 


An important benefit of the object-oriented style is that it lends itself to a par- 
ticularly simple and lucid kind of modularity. If you have modular program- 
ming constructs and techniques available, they help and encourage you to write 
programs that are easy to read and understand, and so are more reliable and 
maintainable. Object-oriented programming lets a programmer implement a 
useful facility that presents the caller with a set of external interfaces, without 
requiring the caller to understand how the internal details of the implementa- 
tion work. In other words, a program that calls this facility can treat the facility 
as a black box; the calling program has an implicit contract with the facility 
guaranteeing the external interfaces, and that is all it knows. 

For example, a program that uses disembodied property lists never needs 
to know that the property list is being maintained as a list of alternating indica- 
tors and values; the program simply performs the operations, passing them 
inputs and getting back outputs. The program depends only on the external 
definition of these operations: it knows that if it stores a property by doing a 
sett of a getf, and doesn’t remf it (or setf over it), then it can use getf to be 
sure of getting back the same thing which was put in. This hiding of the details 
of the implementation means that someone reading a program that uses disem- 
bodied property lists need not concern himself with how they are implemented; 
he need only understand what abstract operations are represented. This lets the 
programmer concentrate his energies on building a higher-level program rather 
than understanding the implementation of the support programs. This hiding of 
implementation means that the representation of property lists could be 
changed and the higher-level program would continue to work. For example, 
instead of a list of alternating elements, the property list could be implemented 
as an association list or a hash table. Nothing in the calling program would 
change at all. 

The same is true of , the ship example. The caller is presented with a col- 
lection of operations, such as ship-x-position, ship-y-position, ship-speed, 
and ship-direction; it simply calls these and looks at their answers, without 
caring how they did what they did. In our example above, ship-x-position and 
ship-y-position would be accessor functions, defined automatically by defs- 
truct, while ship-speed and ship-direction would be functions defined by the 
implementor of the ship type. The code might look like this: 


6.2 
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(defstruct ship 
x-position 
y-position 
x-velocity 
y-velocity 
mass) 

(defun ship-speed (ship) 

(sqrt (+ (expt (ship-x-velocity ship) 2) 

(expt (ship-y-velocity ship) 2)))) 

(defun ship-direction (ship) 

(atan (ship-y-velocity ship) 

(ship-x-velocity ship))) 

The caller need not know that the first two functions were structure acces- 
sors and that the second two were written by hand and perform arithmetic. 
Those facts would not be considered part of the black-box characteristics of the 
implementation of the ship type. The ship type does not guarantee which func- 
tions will be implemented in which ways; such aspects are not part of the con- 
tract between ship and its callers. In fact, ship could have been written this 
way instead: 

(defstruct ship 
x-position 
y-position 
speed 
direction 
mass) 

(defun ship-x-velocity (ship) 

(* (ship-speed ship) (cos (ship-direction ship)))) 

(defun ship-y-velocity (ship) 

(* (ship-speed ship) (sin (ship-direction ship)))) 

In this second implementation of the ship type, we have decided to store 
the velocity in polar coordinates instead of rectangular coordinates. This is 
purely an implementation decision. The caller has no idea which of the two 
ways the implementation uses; he just performs the operations on the object by 
calling the appropriate functions. 

We have now created our own types of objects, whose implementations 
are hidden from the programs that use them. Such types are usually referred to 
as abstract types. The object-oriented style of programming can be used to 
create abstract types by hiding the implementation of the operations and simply 
documenting what the operations are defined to do. 
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Some more terminology: the quantities being held by the elements of the 
ship structure are referred to as instance variables. Each instance of a type has 
the same operations defined on it; what distinguishes one instance from another 
(besides ecpiess) is the values that reside in its instance variables. The example 
above illustrates that a caller of operations does not know what the instance 
variables are; our two ways of writing the ship operations have different 
instance variables, but from the outside they have exactly the same operations. 

One might ask: but what if the caller evaluates (svref ship 2) and notices 
that he gets back the x-velocity rather than the speed? Then he can tell which 
of the two implementations were used. This is true; if the caller were to do that, 
he could tell. However, when a facility is implemented in the object-oriented 
style, only certain functions are documented and advertised, the functions that 
are considered to be operations on the type of object. The contract from ship to 
its callers only speaks about what happens if the caller calls these functions. 
The contract makes no guarantees at all about what would happen if the caller 
were to start poking around on his own using svref. A caller who does so is in 
error. He is depending on the concrete implementation of the abstraction: 
something that is not specified in the contract. No guarantees were ever made 
about the results of such action, and so anything may happen; indeed, if ship 
were reimplemented, the code that does the svref might have a different effect 
entirely and probably stop working. This example shows why the concept of a 
contract between a callee and a caller is important: the contract specifies the 
interface between the two modules. 

Unlike some other languages that provide abstract types, Tek COMMON 
LISP makes no attempt to have the language automatically forbid constructs 
that circumvent the contract. This is intentional. One reason for this is that 
LISP is an interactive system, and so it is important to be able to examine and 
alter internal state interactively (usually from a debugger). Furthermore, there 
is no strong distinction between the system and the user portions of the Tek 
COMMON Lisp system; users are allowed to get into nearly any part of the 
language system and change what they want to change. 

In summary: by defining a set of operations and making only a specific set 
of external entry-points available to the caller, the programmer can create his 
own abstract types. These types can be useful facilities for other programs and 
programmers. Since the implementation of the type is hidden from the callers, 
modularity is maintained and the implementation can be changed easily. 

We have hidden the implementation of an abstract type by making its 
operations into functions which the user may call. The importance of the con- 
cept is not that they are functions — in LISP everything is done with functions. 
The important point is that we have defined a new conceptual operation and 
given it a name, rather than requiring each user who wants to do the operation 
to write it out step-by-step. Thus we say (ship-x-velocity s) rather than (aref s 
2 ). 

Often a few abstract operation functions are simple enough that it is desir- 
able to compile special code for them rather than really calling the function. 
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6.3 

Generic 

operations 


(Compiling special code like this is often called open-coding .) The compiler is 
directed to do this through use of macros for example, defstruct arranges for 
this kind of special compilation for the functions that get the instance variables 
of a structure. 

When we use this optimization, the implementation of the abstract type is 
only hidden in a certain sense. It does not appear in the LISP code written by 
the user, but does appear in the compiled code. The reason is that there may be 
some compiled functions that use the macros (or other concrete manifestation 
of the implementation). Even if you change the definition of the macro, the 
existing compiled code will continue to use the old definition. Thus, if the 
implementation of a module is changed, programs that use it may need to be 
recompiled. This sacrifice of compatibility between interpreted and compiled 
code is usually quite acceptable for the sake of efficiency in debugged code. 

In the Tek COMMON LISP implementation of Flavors that is discussed 
below, there is never any such incorporation of nonmodular knowledge into a 
program by either the interpreter or the compiler, except when the :ordered- 
instance-variables feature is used (described below). If you don’t use the 
:ordered-instance-variables feature, you don’t have to worry about incompa- 
tibilities. 


Consider the rest of the program that uses the ship abstraction. It may want to 
deal with other objects that are like ships in that they are movable objects with 
mass, but unlike ships in other ways. A more advanced model of a ship might 
include the concept of the ship’s engine power, the number of passengers on 
board, and its name. An object representing a meteor probably would not have 
any of these, but might have another attribute such as how much iron is in it. 

However, all kinds of movable objects have positions, velocities, and 
masses, and the system will contain some programs that deal with these quanti- 
ties in a uniform way, regardless of what kind of object is being modeled. For 
example, a piece of the system that calculates every object’s orbit in space 
need not worry about the other, more peripheral attributes of various types of 
objects; it works the same way for all objects. Unfortunately, a program that 
tries to calculate the orbit of a ship needs to know the ship’s attributes, and 
must therefore call ship-x-position and ship-y-velocity and so on. The prob- 
lem is that these functions won’t work for meteors. There would have to be a 
second program to calculate orbits for meteors that would be exactly the same, 
except that where the first one calls ship-x-position, the second one would call 
meteor-x-position, and so on. This would be very bad; a great deal of code 
would have to exist in multiple copies, all of it would have to be maintained in 
parallel, and it would take up space for no good reason. 

What is needed is an operation that can be performed on objects of several 
different types. For each type, it should do the thing appropriate for that type. 
Such operations are called generic operations. The classic example of generic 
operations is the arithmetic functions in many programming languages, 
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including Tek COMMON LISP. The + function accepts integers, floats or big- 
nums and performs an appropriate kind of addition based on the data types of 
the objects being manipulated. In MACSYMA, a large algebraic manipulation 
system implemented in LISP, the + operation works for matrices, polynomials, 
rational functions, and arbitrary algebraic expression trees. In our example, we 
need a generic x-position operation that can be performed on either ships, 
meteors, or any other kind of mobile object represented in the system. This 
way, we can write a single program to calculate orbits. When it wants to know 
the x position of the object it is dealing with, it simply invokes the generic x- 
position operation on the object, and whatever type of object it has, the correct 
operation is performed, and the x position is returned. 

In the following discussion we use another idiom adopted from the 
Smalltalk language: performing a generic operation is called sending a 
message. The message consists of an operation name (a symbol) and argu- 
ments. One can imagine objects in the program as Tittle people’ who accept 
messages and respond to them with answers (returned values). In the example 
above, an object is sent an x-position message, to which it responds with its x 
position. 

Sending a message is a way of invoking a function without specifying 
which function is to be called. Instead, the data determines the function to use. 
The caller specifies an operation name and an object; that is, it said what opera- 
tion to perform, and what object to perform it on. The function to invoke is 
found from this information. 

The two data used to figure out which function to call are the type of the 
object, and the name of the operation. The same set of functions are used for 
all instances of a given type, so the type is the only attribute of the object used 
to figure out which function to call. The rest of the message besides the opera- 
tion is data which are passed as arguments to the function, so the operation is 
the only part of the message used to find the function. Such a function is called 
a method. For example, if we send an x-position message to an object of type 
ship, then the function we find is the ship type’s x-position method. A method 
is a function that handles a specific operation on a specific kind of object; this 
method handles messages named x-position to objects of type ship. 

In our new terminology: the orbit-calculating program finds the x position 
of the object it is working on by sending that object a message consisting of the 
operation x-position and no arguments. The returned value of the message is 
the x position of the object. If the object was of type ship, then the ship type’s 
x-position method was invoked; if it was of type meteor, then the meteor 
type’s x-position method was invoked. The orbit-calculating program just 
sends the message, and the right function is invoked based on the type of the 
object. We now have true generic functions, in the form of message passing: 
the same operation can mean different things depending on the type of the 
object. 


1 .Ml 



Tektronix, Inc. 
6-8 Flavors 


6.4 

Generic 
operations in 
LISP 


How do we implement message passing in LISP? Our convention is that 
objects that receive messages are always functional objects (that is, you can 
apply them to arguments). A message is sent to an object by calling that object 
as a function, passing the operation name as the first argument and the argu- 
ments of the message as the rest of the arguments. Operation names are 
represented by symbols; normally these symbols are in the keyword package, 
since messages may normally be passed between objects defined in different 
packages. So if we have a variable my-ship whose value is an object of type 
ship, and we want to know its x position, we send it a message as follows: 

(send my-ship :x-position) 

To set the ship’s x position to 3.0, we send it a message like this: 

(send my-ship :set-x-position 3.0) 

A variation supported in some Flavor systems would allow 

(send my-ship :set :x-position 3.0) 

;;; not supported 

but this is now deprecated and not provided in Tek COMMON LISP. 

It should be stressed that no new features are added to LISP for message 
sending; we simply define a convention on the way objects take arguments. 
The convention says that an object accepts messages by always interpreting its 
first argument as an operation name. The object must consider this operation 
name, find the function which is the method for that operation, and invoke that 
function. 

To emphasize the relationship between well-known features and the new 
object-oriented version, we define the two basic functions for message passing 
as follows: 

send object message &rest arguments [Function] 

■ This function is equivalent to funcall; however, send may be more 
efficient in some implementations because funcail must determine the 
type of object it is passed, whereas send can assume that object is a flavor 
instance. In any case, the function send is preferable to funcall when a 
message is being sent, since it documents that Flavors and message send- 
ing are being used. 

□ Conceptually, this sends object a message with operation and argu- 
ments as specified. 

□ In some implementations of Flavors, the semantics of send may differ 
from funcall in those cases where object is a symbol, list, number, or 
other object that does not normally handle messages. 
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lexpr-send object message arguments* list-of-arguments [Macro] 

■ This function is equivalent to apply; see the notes above for send. 

The last argument should be a list. 

How does this all work? The object must somehow find the right method for 
the message it is sent. Furthermore, the object now has to be callable as a func- 
tion. However, an ordinary function will not do: we need a data structure that 
can store the instance variables (the internal state) of the object. Of the Tek 
COMMON LISP features available, the most appropriate is the closure. A 
message-receiving object could be implemented as a closure over a set of 
instance variables. The function inside the closure would have a big case form 
to dispatch on its first argument. 

While using closures would work, it has several problems. The main 
problem is that in order to add a new operation to a system, it is necessary to 
modify code in more than one place: you have to find all the types that under- 
stand that operation, and add a new clause to the case. The problem with this 
is that you cannot textually separate the implementation of your new operation 
from the rest of the system: the methods must be interleaved with the other 
operations for the type. Adding a new operation should only require adding 
LISP code; it should not require modifying LISP code. 

For example, the conventional way of making generic operations for arith- 
metic on various new mathematical objects is to have a procedure for each 
operation (+, *, etc), which has a big case for all the types; this means you 
have to modify code in generic-plus, generic-times, ... to add a type. This is 
inconvenient and error-prone. 

The flavor mechanism is a streamlined, more convenient, and time-tested 
system for creating message-receiving objects. With flavors, you can add a 
new method simply by adding code, without modifying existing code. Further- 
more, many common and useful things are very easy to do with flavors. The 
rest of this chapter describes flavors. 


A flavor, in its simplest form, is a definition of an abstract type. New flavors 
are created with the defflavor special form, and methods of the flavor are 
created with the defmethod special form. New instances of a flavor are 
created with the make-instance function. This section explains simple uses of 
these forms. 

For an example of a simple use of flavors, here is how the ship example 
above would be implemented. 
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(defflavor ship (x-position 
y-position 
x-velocity 
y-velocity 
mass) 

0 

:gettable-instance-variables) 

(defmethod (ship :speed) () 

(sqrt (+ (expt x-velocity 2) 

(expt y-velocity 2)))) 

(defmethod (ship :direction) () 

(atan y-velocity x-velocity)) 

The code above creates a new flavor. The first subform of the defflavor 
is ship, which is the name of the new flavor. Next is the list of instance vari- 
ables; they are the five that should be familiar by now. The next subform is 
something we will get to later. The rest of the subforms are the body of the 
defflavor, and each one specifies an option about this flavor. In our example, 
there is only one option, namely :gettable-instance-variables . This means 
that for each instance variable, a method should automatically be generated to 
return the value of that instance variable. The name of the operation is a sym- 
bol with the same name as the instance variable, but interned in the keyword 
package. Thus, methods are created to handle the operations :x-position, :y- 
position, and so on. 

Each of the two defmethod forms adds a method to the flavor. The first 
one adds a handler to the flavor ship for the operation :speed. The second 
subform is the lambda-list, and the rest is the body of the function that handles 
the :speed operation. The body can refer to or set any instance variables of 
the flavor, just like variables bound by a containing let. When any instance of 
the ship flavor is invoked with a first argument of direction, the body of the 
second defmethod is evaluated in an environment in which the instance vari- 
ables of ship refer to the instance variables of this instance (the one to which 
the message was sent). So the arguments passed to atan are the the velocity 
components of this particular ship. The result of atan becomes the value 
returned by the ; direction operation. 

Now we have seen how to create a new abstract type: a new flavor. Every 
instance of this flavor has the five instance variables named in the defflavor 
form, and the seven methods we have seen (five that were automatically 
generated because of the :gettable-instance-variables option, and two that 
we wrote ourselves). The way to create an instance of our new flavor is with 
the make-instance function. Here is how it could be used: 

(setq my-ship (make-instance ’ship)) 
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This returns an object whose printed representation is something like 
#<ship 13731210>. (The details of the print form will vary; it is an object 
which cannot be read back in from this default short-hand printed representa- 
tion.) The argument to make-instance is the name of the flavor to be instan- 
tiated. Additional arguments, not used here, are init options, that is, commands 
to the flavor of which we are making an instance, selecting optional features. 
This will be discussed more in a moment. 

Examination of the flavor we have defined shows that it is quite useless as 
it stands, since there is no way to set any of the parameters. We can fix this up 
easily by putting the isettable-instance-variables option into the defflavor 
form. This option tells defflavor to generate methods for operations :set-x- 
position, :set-y-position, and so on. Each such method takes one argument 
and sets the corresponding instance variable to that value. 

Another option we can add to the defflavor is :initable-instance- 
variables, (alternative spelling for compatibility is :inittable-instance- 
variables ) which allows us to initialize the values of the instance variables 
when an instance is first created. :initable-instance-variables does not create 
any methods; instead, it makes initialization keywords named :x-position, :y- 
position, etc., that can be used as init-option arguments to make-instance to 
initialize the corresponding instance variables. The list of init options is some- 
times called the init-plist because it is like a property list. 

Here is the improved defflavor: 

(defflavor ship (x-position 
y-position 
x-velocity 
y-velocity 
mass) 

0 

:gettable-instance-variables 

:settable-instance-variables 

:initable-instance-variables) 

All we have to do is evaluate this new defflavor, and the existing flavor 
definition is updated and now includes the new methods and initialization 
options. In fact, the instance we generated a while ago now accepts the new 
operations! We can set the mass of the ship we created by evaluating: 

(send my-ship :set-mass 3.0) 

and the mass instance variable of my-ship is properly set to 3.0. 

If you want to play around with flavors, it is useful to know that describe 
of an instance tells you the flavor of the instance and the values of its instance 
variables. If we were to evaluate (describe my-ship) at this point, the following 
would be printed: 
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#<ship 3214320>, an object of flavor ship, 
has instance variable values : 


x-position: 

nil 

y-position: 

* nil 

x-velocity: 

nil 

y-velocity : 

nil 

mass : 

3.0 


Now that the instance variables are initable, we can create another ship 
and initialize some of the instance variables using the init-plist. Let’s do that 
and describe the result: 


<cl> (setq her-ship 

(make-instance ' ship 

: x-position 0.0 
: y-position 2 . 0 
:mass 3.5)) 

#<ship 3242340 

<cl> (describe her-ship) 

#<ship 3242340>, an object of flavor ship, 
has instance variable values : 


x-position: 

0.0 

y-position: 

2.0 

x-velocity: 

nil 

y-velocity: 

nil 

mass : 

3.5 


A flavor can also establish default initial values for instance variables. 
These default values are used when a new instance is created if the values are 
not initialized any other way. The syntax for specifying a default initial value 
is to replace the name of the instance variable by a list, whose first element is 
the name and whose second is a form to evaluate to produce the default initial 
value. For example when read in the definitions: 

(defvar *default-x-velocity* 2.0) 

(defvar *default-y-velocity* 3.0) 

(defflavor ship ((x-position 0.0) 

(y-position 0.0) 

(x-velocity *default-x-velocity*) 

(y-velocity *default-y-velocity*) 
mass) 

0 

:gettable-instance-variables 

:settable-instance-variables 
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:initable-instance-variables) 
Then the results are as follows: 


<cl> (setq another-ship 

(make-instance 'ship : x-position 3.4)) 

#<ship 2342340> 

<cl> (describe another-ship) 

#<ship 2342340 
an object of flavor ship, 
has instance variable values : 


x-position : 

3.4 

y-position: 

0.0 

x-velocity : 

2.0 

y-velocity : 

3.0 

mass : 

nil 


The value of x-position was initialized explicitly, so the default was 
ignored. The value of y-position was initialized from the default value, which 
was 0.0. The two velocity instance variables were initialized from their default 
values, which came from two global variables. The value of mass was not 
explicitly initialized and did not have a default initialization, so it was left as 
nil. Some flavor implementations set an uninitialized instance variable to 
unbound rather than nil. 

There are many other options that can be used in defflavor, and the init 
options can be used more flexibly than just to initialize instance variables; full 
details are given later in this chapter. But even with the small set of features 
we have seen so far, it is easy to write object-oriented programs. 


Now we have a system for defining message-receiving objects so that we can 
have generic operations. If we want to create a new type called meteor that 
would accept the same generic operations as ship, we could simply write 
another defflavor and two more defmethods that looked just like those of 
ship, and then meteors and ships would both accept the same operations. 
Objects of type ship would have some more instance variables for holding attri- 
butes specific to ships and some more methods for operations that are not 
generic, but are only defined for ships; the same would be true of meteor. 

However, this would be a a wasteful thing to do. The same code has to be 
repeated in several places, and several instance variables have to be repeated. 
The code now needs to be maintained in many places, which is always undesir- 
able. The power of flavors (and the name flavors) comes from the ability to 
mix several flavors and get a new flavor. Since the functionality of ship and 
meteor partially overlap, we can take the common functionality and move it 
into its own flavor, which might be called moving-object. We would define 
moving-object the same way as we defined ship in the previous section. Then, 
ship and meteor could be defined like this: 
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(defflavor ship (engine-power 

number-of-passengers 

name) 

(moving-object) 

:gettable-instance-variables) 

(defflavor meteor (percent-iron) 

(moving-object) 

:initable-instance-variables) 

These defflavor forms use the second subform, for which we previously 
used (). The second subform is a list of flavors to be combined to form the new 
flavor; such flavors are called components. Concentrating on ship for a 
moment (analogous statements are true of meteor), we see that it has exactly 
one component flavor: moving-object. It also has a list of instance variables, 
which includes only the ship-specific instance variables and not the ones that it 
shares with meteor. By incorporating moving-object, the ship flavor acquires 
all of its instance variables, and so need not name them again. It also acquires 
all of moving-objects methods, too. So with the new definition, ship instances 
still implement the :x-velocity and :speed operations, with the same meaning 
as before. However, the :engine-power operation is also understood (and 
returns the value of the engine-power instance variable). 

What we have done here is to take an abstract type, moving-object, and 
build two more specialized and powerful abstract types on top of it. Any ship 
or meteor can do anything a moving object can do, and each also has its own 
specific abilities. This kind of building can continue; we could define a flavor 
called ship-with-passenger that was built on top of ship, and it would inherit all 
of moving-objects instance variables and methods as well as ships instance 
variables and methods. Furthermore, the second subform of defflavor can be a 
list of several components, meaning that the new flavor should combine all the 
instance variables and methods of all the flavors in the list, as well as the ones 
those flavors are built on, and so on. All the components taken together form a 
big tree of flavors. A flavor is built from its components, its components’ com- 
ponents, and so on. We sometimes use the term components to mean the 
immediate components (the ones listed in the defflavor), and sometimes to 
mean all the components (including the components of the immediate com- 
ponents and so on). (Actually, it is not strictly a tree, since some flavors might 
be components through more than one path. It is really a directed graph; it can 
even be cyclic.) 

The order in which the components are combined to form a flavor is 
important. The tree of flavors is turned into an ordered list by performing a 
top-down, depth-first walk of the tree, including non-terminal nodes before the 
subtrees they head, ignoring any flavor that has been encountered previously 
somewhere else in the tree. For example, if flavor-1 s immediate components 
are flavor-2 and flavor-3, and flavor-2s components are flavor-4 and flavor-5, 
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and flavor-3s component was flavor-4, then the complete list of components of 
flavor-1 would be: (flavor-1, flavor-2, flavor-4, flavor-5, flavor-3). The flavors 
earlier in this list are the more specific, less basic ones; in our example, ship- 
with-passengers would be first in the list, followed by ship, followed by 
moving-object. A flavor is always the first in the list of its own components. 
Notice that flavor-4 does not appear twice in this list. Only the first occurrence 
of a flavor appears; duplicates are removed. (The elimination of duplicates is 
done during the walk; a cycle in the directed graph does not cause a non- 
terminating computation.) 

The set of instance variables for the new flavor is the union of all the sets 
of instance variables in all the component flavors. If both flavor-2 and flavor-3 
have instance variables named foo, then flavor-1 has an instance variable 
named foo, and all methods that refer to foo refer to this same instance vari- 
able. Thus different components of a flavor can communicate with one another 
using shared instance variables. (Often, only one component ever sets the vari- 
able; the others only look at it.) The default initial value for an instance vari- 
able comes from the first component flavor to specify one. 

The way the methods of the components are combined is the heart of the 
flavor system. When a flavor is defined, a single function, called a combined 
method, is constructed for each operation supported by the flavor. This func- 
tion is constructed out of all the methods for that operation from all the com- 
ponents of the flavor. There are many different ways that methods can be com- 
bined; these can be selected by the user when a flavor is defined. The user can 
also create new forms of combination. 

There are several kinds of methods, but so far, the only kinds of methods 
we have seen are primary methods. The default way primary methods are 
combined is that all but the earliest one provided are ignored. In other words, 
the combined method is simply the primary method of the first flavor to pro- 
vide a primary method. What this means is that if you are starting with a flavor 
foo and building a flavor bar on top of it, then you can override foos method for 
an operation by providing your own method. Your method will be called, and 
foo’s will never be called. 

Simple overriding is often useful; for example, if you want to make a new 
flavor bar that is just like foo except that it reacts completely differently to a 
few operations. However, often you don’t want to completely override the 
base flavor’s (foo’s) method; sometimes you want to add some extra things to 
be done. This is where combination of methods is used. 

The usual way methods are combined is that one flavor provides a 
primary method, and other flavors provide daemon methods. The idea is that 
the primary method is in charge of the main business of handling the operation, 
but other flavors just want to keep informed that the message was sent, or just 
want to do the part of the operation associated with their own area of responsi- 
bility. 

daemon methods come in two kinds, before and after. There is a special 
syntax in defmethod for defining such methods. Here is an example of the 
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syntax. To give the ship flavor an after-daemon method for the :speed opera- 
tion, the following syntax would be used: 

(defmethod (ship :after :speed) (body)) 

Now, when a message is sent, it is handled by a new function called the 
combined method. The combined method first calls all of the before daemons, 
then the primary method, then all the after daemons. Each method is passed 
the same arguments that the combined method was given. The returned values 
from the combined method are the values returned by the primary method; any 
values returned from the daemons are ignored. Before-daemons are called in 
the order that flavors are combined, while after-daemons are called in the 
reverse order. In other words, if you build bar on top of too, then bar’s 
before-daemons run before any of those in too, and bars after-daemons run 
after any of those in foo. 

The reason for this order is to keep the modularity order correct. If we 
create fiavor-1 built on flavor-2, then the components of flavor-2 should not 
matter. Our new before-daemons go before all methods of flavor-2, and our 
new after-daemons go after all methods of flavor-2. Note that if you have no 
daemons, this reduces to the form of combination described above. The most 
recently added component flavor is the highest level of abstraction; you build a 
higher-level object on top of a lower-level object by adding new components to 
the front. The syntax for defining daemon methods can be found in the 
description of defmethod below. 

To make this a bit more clear, let’s consider a simple example that is easy 
to play with: the :print-self method. The LISP printer (i.e. the print function) 
prints instances of flavors by sending them :print-self messages. The first 
argument to the :print-self operation is a port (we can ignore the others for 
now), and the receiver of the message is supposed to print its printed represen- 
tation on the port. In the ship example above, the reason that instances of the 
ship flavor printed the way they did is because the ship flavor was actually 
built on top of a very basic flavor called vanilla-flavor; this component is pro- 
vided automatically by defflavor. It was vanilla-flavor’s :print-self method 
that was doing the printing. Now, if we give ship its own primary method for 
the :print-self operation, then that method completely takes over the job of 
printing: vanilla-flavors method will not be called at all. However, if we give 
ship a before-daemon method for the ; print-self operation, then it will get 
invoked before the vanilla-flavor method, and so whatever it prints will appear 
before what vanilla-flavor prints. So we can use before-daemons to add pre- 
fixes to a printed representation; similarly, after-daemons can add suffixes. 

There are other ways to combine methods besides daemons, but this way 
is the most common. The more advanced ways of combining methods are 
explained in a later section. The details of vanilla-flavor and what it does for 
you are also explained later. 
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We’ve been using the following special form informally: 

defflavor flavor-name (vars*) (flavors*) options* [Macro] 

■ WHERE flavor-name is a symbol which serves to name this flavor. 

□ The vars are the names of the instance-variables containing the local 
state for this flavor. A list of two elements: the name of an instance- 
variable and a default initialization form is also acceptable; the initializa- 
tion form is evaluated when an instance of the flavor is created if no other 
initial value for the variable is obtained. If no initialization is specified, 
the variable has value nil. 

□ The flavors are the names of the component flavors out of which this 
flavor is built. The features of those flavors are inherited as described pre- 
viously. 

□ Each of the options may be either a keyword symbol or a list of a key- 
word symbol and arguments. The options to defflavor are described 
under §6.8, Defflavor options, below. 

□ type-of applied to an instance returns the symbol which is the name of 
its flavor. 

■ SIDE effect: The symbol flavor-name is given a flavor property which 
is the internal data-structure containing the details of the flavor. 

■ NOTE: In Tek COMMON LISP objects which are instances of flavors are 
implemented by a hidden internal data type, actually a kind of vector. The 
svref function can access the slots of an instance. The zeroth slot points 
to the internal descriptor for that flavor; successive slots hold the instance 
variables. 

*all-flavor-names* [Variable] 

■ A special variable containing a list of the names of all flavors that have 
ever been defflavored. 

def method (flavor-name [method-type] operation) lambda-list [Macro] 

forms* 

■ WHERE flavor-name is a symbol which is the name of the flavor which 
is to receive the method, operation is a keyword symbol which names the 
operation to be handled, method-type is a keyword symbol for the type of 
method; it is omitted when you are defining a primary method. For some 
method-types, additional information is expected. It comes after opera- 
tion. 

■ SIDE EFFECT: defmethod defines a method, that is, a function to han- 
dle a particular operation for instances of a particular flavor. The meaning 
of method-type depends on what style of method combination is declared 
for this operation. For instance, if : daemon combination (the default 
style) is in use, method types ’.before and ’.after are allowed. See §6.11 
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below on Method combination for a complete description of the way 
methods are combined. 

□ lambda-list describes the arguments and &aux variables of the func- 
tion. The first argument to the method, which is the operation name itself, 
is automatically handled and so is not included in lambda-list. Note that 
methods may not have unevaluated arguments; that is, they must be func- 
tions, not macros or special forms. The forms are the function body; the 
value of the last form is returned when the method is applied. Some 
methods can return multiple values, depending on the style of method 
combination used. 

□ The variant form 

(defmethod (flavor-name operation) function) 

where function is a symbol, says that flavor-names method for operation is 
function, a symbol which names a function. When function is called, self 
and any special instance variables will be bound. The function must take 
appropriate arguments; the first argument is the operation. Various flavor 
implementations have different conventions for automatically-supplied 
arguments to method functions; these should be conditionalized if code 
must be transportable. 

If you redefine a method that is already defined, the new definition replaces the 
old one. Given a flavor, an operation name, and a method type, there can only 
be one function (with the exception of ;case methods), so if you define a 
:before daemon method for the foo flavor to handle the :bar operation, then 
you replace the previous before-daemon; however, you do not affect the 
primary method or methods of any other type, operation or flavor. 

Along with other things, defmethod causes a function to be detuned. 
The function name is formed by concatenating the hyphen-separated print 
names of all the symbols in the first defmethod subform, then suffixing 
-method', this name is interned in the same package as the flavor name. For 
example, (defmethod (foo :before :bar) ...) defines a function named foo- 
before-bar-method. This is useful to know if you want to trace a method, or if 
you want to poke around at the method function itself. 

make-instance flavor-name {init-option value}* [Function] 

■ RETURNS an instance of the specified flavor which has just been 
created. 

□ Arguments after the first are alternating init-option keywords and argu- 
ments to those keywords. These options are used to initialize instance 
variables and to select arbitrary options, as described above. An :init 
message is sent to the newly-created object with one argument, the init- 
plist. This is a property-list containing the init-options specified and those 
defaulted from the flavor’s :default-init-plist (however, init keywords 


D-01 -02(26-1! 



Tek Common Lisp 
F lavors 6-19 


that simply initialize instance variables, and the corresponding values, 
may be absent when the :init methods are called), make-instance is an 
easy-to-call interface to instantiate-flavor, below. 

instantiate-flavor flavor-name init-plist &optional send-init- [Function] 
message-p return-unhandled-keywords area 

■ Returns a new instance of flavor flavor-name. 

■ NOTE: This is an extended version of make-instance, giving you more 
features. Note that it takes the init-plist as an individual argument, rather 
than taking a &rest argument of init options and values. 

This property list can be modified; the properties from the default init-plist are 
added on if not already present, and some Unit methods may do explicit (setf 
(getf ...)) onto the init-plist. 

In the event that :init methods remprop properties already on the init-plist, 
as opposed to simply doing (setf (getf ...)), then the init-plist is rplacded. This 
means that the actual supplied list of options is modified, so this list should not 
be one contained inside a body of code. This would permanently modify the 
calling code. Therefore for each call of instantiate-flavor the caller should 
recreate or otherwise copy (e.g. with append) the list to be passed as the init- 
plist argument. 

Do not use nil as the init-plist argument. This would mean to use the pro- 
perties of the symbol nil as the init options. If your goal is to have no init 
options, you must provide a property list containing no properties, such as the 
list (nil), which can be created by evaluating the form (list nil). 

Here is the sequence of actions by which instantiate-flavor creates a new 
instance: 

1 The specified flavor’s instantiation flavor function, if it exists, is called to 
determine which flavor should actually be instantiated. If there is no 
instantiation flavor function, the specified flavor is instantiated. 

If the flavor’s method hash-table and other internal information have not 
been computed or are not up to date, they are computed. This may take a 
substantial amount of time, but it happens only once for each time you 
define or redefine a particular flavor. 

2 The instance itself is created. The area argument is ignored by Tek COM- 
MON LISP and refers to consing in specified areas, a feature used in some 
LISP machines. 

3 Initial values of the instance variables are computed. If an instance vari- 
able is declared initable, and a keyword with the same spelling as its name 
appears in init-plist, the property for that keyword is used as the initial 
value. 

Otherwise, if the default init-plist specifies such a property, the value form 
is evaluated and the result used. Otherwise, if the flavor definition speci- 
fies a default initialization form, it is evaluated and that result is used. In 
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either case, the initialization forms may not refer to any instance variables, 
nor will they find the variable self be bound to the new instance. The 
value forms are evaluated before the instance is actually allocated. 

If an instance variable does not get initialized either of these ways it is left 
nil; an :init method may initialize it (see below). 

All remaining keywords and values specified in the :default-init-plist 
option to defflavor, that do not initialize instance variables and are not 
overridden by anything explicitly specified in init-plist are then merged 
into init-plist using setf of getf. The default init plist of the instantiated 
flavor is considered first, followed by those of all the component flavors 
in the standard order. 

4 Keywords appearing in the init-plist but not defined with the unit- 
keywords option or the :initable-instance-variables option for some 
component flavor are collected. If the :allow-other-keys option is speci- 
fied with a non -nil value (either in the original init-plist argument or by 
some default init plist) then these unhandled keywords are ignored. If the 
return-unhandled-keywords argument is non-nil, a list of these keywords 
is returned as the second value of instantiate-flavor. Otherwise, an error 
is signaled if any unrecognized init keywords are present. 

5 If the send-init-message-p argument is supplied and non-nil, an :init 
message is sent to the newly-created instance, with one argument, the init- 
plist. getf can be used to extract options from this property-list. Each fla- 
vor that needs initialization can contribute an ;/n/f method by defining a 
daemon. 

The :init methods should not look on the init-plist for keywords that simply ini- 
tialize instance variables (that is, keywords defined with :initable-instance- 
variables rather than :init-keywords ). The corresponding instance variables 
are already set up when the :init methods are called, and sometimes the key- 
words and their values may actually be missing from the init-plist if it is more 
efficient not to put them on. To avoid problems, always refer to the instance 
variables themselves rather than looking for the init keywords that initialize 
them. 

:init init-plist [Message] 

■ This operation is implemented on all flavor instances. 

■ SIDE EFFECT: This function examines the init keywords and perform 
whatever initializations are appropriate, init-plist is the argument that was 
given to instantiate-flavor, and may be passed directly to getf to examine 
the value of any particular init option. 

□ The default definition of this operation does nothing. However, many 
flavors add : before and ; after daemons to it. 
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exchinstancep object [Function] 

■ RETURNS t if object is an instance of a flavor. 

defwrapper (flavor-name operation) lambda-list &body body [Macro] 

■ NOTE: This feature is complex and you may not be able to understand 
it completely until you have gained some experience with flavors. It can 
safely be skipped meanwhile. 

□ Sometimes the way the flavor system combines the methods of dif- 
ferent flavors (the daemon system) is not powerful enough. In that case 
defwrapper can be used to define a macro that expands into code that is 
wrapped around the invocation of the methods. This is best explained by 
an example; suppose you needed a lock locked during the processing of 
the :foo operation on flavor bar, which takes two arguments, and you 
have a lock-frobboz special-form that knows how to lock the lock 
(presumably it generates an unwind-protect), lock-frobboz needs to see 
the first argument to the operation; perhaps that tells it what sort of opera- 
tion is going to be performed (read or write). 

(defwrapper (bar :foo) ((argl arg2) . body) 

‘(lock-frobboz (self argl) 

• .body)) 

The use of the body macro-argument prevents the macro defined by 
defwrapper from knowing the exact implementation and allows several 
defwrappers from different flavors to be combined properly. 

Note that the argument variables, argl and arg2, are not referenced 
with commas before them. These may look like defmacro argument vari- 
ables, but they are not. Those variables are not bound at the time the 
defwrapper-defined macro is expanded and the back-quoting is done; 
rather, the result of that macro-expansion and back-quoting is code which, 
when a message is sent, will bind those variables to the arguments in the 
message as local variables of the combined method. 

Consider another example. Suppose you thought you wanted a 
‘.before daemon, but found that if the argument was nil you needed to 
return from processing the message immediately, without executing the 
primary method. You could write a wrapper such as: 

(defwrapper (bar :foo) ((argl) . body) 

‘(cond ((null argl)) 

(t (print "About to do :FOO") 

• .body))) 

Suppose you need a variable for communication among the daemons for a 
particular operation; perhaps the :after daemons need to know what the 
primary method did, and it is something that cannot be easily deduced 
from just the arguments. You might use an instance variable for this, or 
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you might create a special variable which is bound during the processing 
of the operation and used free by the methods. 

(defvar *communication*) 

(defwrapper (bar :foo) (ignore . body) 

‘(let ((*communication* nil)) 

• .body)) 

Similarly you might want a wrapper that puts a catch around the pro- 
cessing of an operation so that any one of the methods could throw out in 
the event of an unexpected condition. 

Like daemon methods, wrappers work in outside-in order; when you 
add a defwrapper to a flavor built on other flavors, the new wrapper is 
placed outside any wrappers of the component flavors. However, all 
wrappers happen before any daemons happen. When the combined 
method is built, the calls to the before-daemon methods, primary methods, 
and after-daemon methods are all placed together, and then the wrappers 
are wrapped around them. Thus, if a component flavor defines a wrapper, 
methods added by new flavors execute within that wrapper’s context. 

Be careful about inserting the body into an internal lambda- 
expression within the wrapper’s code. Doing so interacts with the inter- 
nals of the flavor system and requires knowledge of things not docu- 
mented in the manual in order to work properly. 

defwhopper (flavor-name operation) lambda-list &body body [Macro] 

■ NOTE: Whoppers are a feature of some flavor implementations which 
do many of the same things as wrappers. They will be documented when 
they are implemented in Tek COMMON LISP. 

undefmethod flavor [type] operation [suboperation] [Macro] 

■ Removes a method: (undefmethod (flavor :before '.operation)) removes 
the method created by (defmethod (flavor :before operation) ...). To 
remove a wrapper, use undefmethod with : wrapper as the method type. 

undefflavor flavor [Function] 

■ Undefines flavor flavor. All methods of the flavor are lost, flavor and 
all flavors that depend on it are no longer valid to instantiate. If instances 
of the discarded definition exist, they continue to use that definition. 

seif [Variable] 

■ When a message is sent to an object, the variable self is automatically 
bound to that object for the benefit of methods which want to manipulate 
the object itself (as opposed to its instance variables), self is a lexical 
variable, that is, its scope of is local to the method body. 
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send instance message [argument ...] [Macro] 

funcall instance message &rest arguments [Function] 

■ NOTE: This is the way a message is passed to an instance of a flavor, 
send and funcall operate in essentially the same manner, send is poten- 
tially slightly more efficient because the evaluator can infer that the func- 
tional argument is an instance, whereas funcall must determine the type 
of its first argument. 


send-self message arguments* [Macro] 

funcall-self message arguments* [Macro] 

lexpr-send-self message arguments* list-of-arguments [Macro] 

lexpr-funcall-self message arguments* list-of-arguments [Macro] 


■ funcall-self is nearly equivalent to funcall with self as the first argu- 
ment, but may be a little faster. The others are analogous. 

recompile-flavor flavor-name &optional single-op use-old- [Function] 

combined-methods do-dependents 

■ Updates the internal data of the flavor and any flavors that depend on 
it. If single-op is supplied non -nil, only the methods for that operation are 
changed. The system does this when you define a new method that did 
not previously exist. If use-old-combined-methods is t, then the existing 
combined method functions are used if possible. New ones are generated 
only if the set of methods to be called has changed. If use-old-combined- 
methods is nil, automatically-generated functions to call multiple methods 
or to contain code generated by wrappers are regenerated unconditionally. 
The default value of use-old-combined-methods is f. If do-dependents is 
nil, only the specific flavor you specified is recompiled. Normally all fla- 
vors that depend on it are also recompiled, i.e. the default value of do- 
dependents is t. 

□ recompile-flavor affects only flavors that have already been compiled. 
Typically this means it affects flavors that have been instantiated, but does 
not bother with mixins. 

compile-flavor-methods flavor-names* [Macro] 

■ The form (compile-flavor-methods flavor-name-1 flavor-name-2 ...), 
placed in a file to be compiled, directs the compiler to perform flavor 
combination for the named flavors, forcing the generation and compilation 
of automatically-generated combined methods at compile time. Further- 
more, the internal data structures needed to instantiate the flavor will be 
computed at load time, rather than waiting for the first attempt to instan- 
tiate the flavor. 

□ You should only use compile-flavor-methods on a flavor that is going 
to be instantiated. For a flavor that is never going to be instantiated (that 
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is, a flavor that only serves to be a component of other flavors that actu- 
ally do get instantiated), it is a complete waste of time, except in the 
unusual case where those other flavors can inherit the combined methods 
of this flavor instead of each one having its own copy of the combined 
method which happens to identical to the others. In this unusual case, you 
should use the ’.abstract-flavor option to defflavor. 

□ compile-flavor-methods forms should be compiled after all of the 
other information needed to create the combined methods is available. 
You should put them after all the definitions of all relevant flavors, 
wrappers, and methods of all components of the argument flavors. 

□ When a compile-flavor-methods form is seen by the interpreter, the 
internal data structures are generated and the combined methods are 
defined. 

get-handler-for object operation [Function] 

■ Given an object and an operation, this returns the object’s method for 
that operation, or nil if it has none. When object is an instance of a flavor, 
this function can be useful to find which of that flavor’s components sup- 
plies the method. 

□ This is equivalent to the :get-handler-for message provided by 
sitvanilla-flavor. 

flavor-allows-init-keyword-p flavor-name keyword [ Function ] 

■ RETURNS non -nil if the flavor named flavor-name allows keyword in 
the init options when it is instantiated, or nil if it does not. The non- nil 
value is the name of the component flavor that contributes the support of 
that keyword. 

si:f!avor-allowed-init-keywords flavor-name [Function] 

■ RETURNS a list of all the init keywords that may be used in instantiat- 
ing flavor-name. 

symeval-in-instance instance symbol &optional no-error-p [Function] 

■ RETURNS the value of the instance variable symbol inside instance. If 
there is no such instance variable, an error is signaled, unless no-error-p is 
non-nil, in which case nil is returned. 

set-in-instance instance symbol value [Function] 

■ SIDE EFFECT: Sets the value of the instance variable symbol inside 
instance to value. If there is no such instance variable, an error is sig- 
naled. 
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describe-flavor flavor-name [Function] 

■ SIDE EFFECT: Prints descriptive information about a flavor; it is self- 
explanatory. An important thing it tells you that can be hard to figure out 
yourself is the combined list of component flavors; this list is what is 
printed after the phrase ‘and directly or indirectly depends on.’ 


There are quite a few options to def flavor. They are all described here, 
although some are for very specialized purposes and not of interest to most 
users. A few options take additional arguments, and these are listed and 
described with the option. 

Several of these options declare things about instance variables. These 
options can be given with arguments which are instance variables, or without 
any arguments in which case they refer to all of the instance variables listed at 
the top of the defflavor. This is not necessarily all the instance variables of the 
combined flavor, just the ones mentioned in this flavor’s defflavor. When 
arguments are given, they must be instance variables that were listed at the top 
of the defflavor; otherwise they are assumed to be misspelled and an error is 
signaled. It is legal to declare things about instance variables inherited from a 
component flavor, but to do so you must list these instance variables explicitly 
in the instance variable list at the top of the defflavor, or mention them in a 
required-instance-variable option. 

:gettable-instance-variables [Defflavor option] 

■ Enables automatic generation of methods for getting the values of 
instance variables. The operation name is the name of the variable, in the 
keyword package (i.e. it has a colon in front of it). 

□ Note that there is nothing special about these methods; you could 
easily define them yourself. This option generates them automatically to 
save you the trouble of writing out a lot of very simple method definitions. 
(The same is true of methods defined by the :settable-instance-variables 
option.) If you define a method for the same operation name as one of the 
automatically generated methods, the explicit definition overrides the 
automatic one. 

:settable-instance-variables [ Defflavor option] 

■ Enables automatic generation of methods for setting the values of 
instance variables. The operation name is :set- followed by the name of 
the variable. All settable instance variables are also automatically made 
gettable and initable. (See the note in the description of the :gettable- 
instance-variables option, above.) 
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:initable-instance-variables [Defflavor option] 

■ The instance variables listed as arguments, or all instance variables 
listed in this defflavor if the keyword is given alone, are made initable. 
This means that they can be initialized through use of a keyword (a colon 
followed by the name of the variable) as an init-option argument to make- 
instance. For compatibility with certain other implementations, the spel- 
ling :inittable-instance-variables is also accepted. 

:special-instance-variables [Defflavor option] 

■ NOTE: Special instance variables are not implemented Tek COMMON 
LISP. Instance variables are scoped lexically inside a method in both com- 
piled and interpreted code. Special instance variables are unimplement- 
able in COMMON Lisp for the same reasons that it is impossible to close 
over a normal special variable. In any case, they are deleterious to proper 
code modularity; the original designers of Flavors now deprecate them as 
a misfeature except for very obscure (or historical) purposes. The Tek 
COMMON Lisp implementation ignores the tspecial-instance-variable 
specification other than issuing a warning message, but the resulting code 
will be unlikely to do the right thing if the instance variables were 
declared special for some particular purpose. 

:init-keywords [Defflavor option] 

■ The arguments are declared to be valid keywords to use in 
instantiate-flavor when creating an instance of this flavor (or any flavor 
containing it). The system uses this for error-checking: before the system 
sends the unit message, it makes sure that all the keywords in the init-plist 
are either initable instance variables or elements of this list. If any is not 
recognized, an error is signaled. When you write a unit method that 
accepts some keywords, they should be listed in the unit-keywords 
option of the flavor. If :allow-other-keys is used as an init keyword with 
a non-nil value, this error check is suppressed. Then unrecognized key- 
words are simply ignored. 

:default-init-plist [Defflavor option] 

■ The arguments are alternating keywords and value forms, like a pro- 
perty list. When the flavor is instantiated, these properties and values are 
put into the init-plist unless already present. This allows one component 
flavor to default an option to another component flavor. The value forms 
are only evaluated when and if they are used. For example, 

(:default-init-plist :frob-array 

(make-array 1 00)) 
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would provide a default frob array for any instance for which the user did 
not provide one explicitly. The following specification prevents errors for 
unhandled init keywords in all instantiations of this flavor and other fla- 

, vors that depend on it. 

(:default-init-plist :allow-other-keys t) 

:required-init-keywords [Defflavor option] 

■ The arguments are init keywords which are to be required each time 
this flavor (or any flavor containing it) is instantiated. An error is signaled 
if any required init keyword is missing. 

‘.required-instance-variables [Defflavor option ] 

■ Declares that any flavor incorporating this one that is instantiated into 
an object must contain the specified instance variables. An error occurs if 
there is an attempt to instantiate a flavor that incorporates this one if it 
does not have these in its set of instance variables. Note that this option is 
not one of those that checks the spelling of its arguments in the way 
described at the start of this section (if it did, it would be useless). 

□ Required instance variables may be freely accessed by methods just 
like normal instance variables. The difference between listing instance 
variables here and listing them at the front of the defflavor is that the 
latter declares that this flavor owns those variables and accepts responsi- 
bility for initializing them, while the former declares that this flavor 
depends on those variables but that some other flavor must be provided to 
manage them and whatever features they imply. 

‘.required-methods [Defflavor option] 

■ The arguments are names of operations that any flavor incorporating 
this one must handle. An error occurs if there is an attempt to instantiate 
such a flavor and it is lacking a method for one of these operations. Typi- 
cally this option appears in the defflavor for a base flavor. Usually this is 
used when a base flavor does a (send self ...) to send itself a message that 
is not handled by the base flavor itself; the idea is that the base flavor will 
not be instantiated alone, but only with other components (mixins) that do 
handle the message. This keyword allows the error of having no handler 
for the message to be detected when the flavor instantiated or when 
compile-flavor-methods is done, rather than when the missing operation 
is used. 



Tektronix, Inc. 
6-28 Flavors 


:required-flavors [Defflavor option] 

■ The arguments are names of flavors that any flavor incorporating this 
one must include as components, directly or indirectly. The difference 
between declaring flavors as required and listing them directly as com- 
ponents at the top of the defflavor is that declaring flavors to be required 
does not make any commitments about where those flavors will appear in 
the ordered list of components; that is left up to whoever does specify 
them as components. Declaring a flavor to be required only provides error 
checking: an attempt to instantiate a flavor that does not include the 
required flavors as components signals an error. Compare this with 
•.required-methods and :required-instance-variables. 

For an example of the use of required flavors, consider the ship example given 
earlier, and suppose we want to define a relativity-mixin which increases the 
mass dependent on the speed. We might write, 

(defflavor relativity-mixin () (moving-object)) 

(defmethod (relativity-mixin :mass) () 

(/ mass (sqrt (- 1 

(expt (/ (send self :speed) 

*speed-of-light*) 

2))))) 

but this would lose because any flavor that had relativity-mixin as a component 
would get moving-object right after it in its component list. As a base flavor, 
moving-object should be last in the list of components so that other components 
mixed in can replace its methods and so that daemon methods combine in the 
right order, relativity-mixin has no business changing the order in which flavors 
are combined, which should be under the control of its caller. For example, 

(defflavor starship () (relativity-mixin 

long-distance-mixin 

ship)) 

puts moving-object last (inheriting it from ship). So instead of the definition 
above we write, 

(defflavor relativity-mixin () 

0 

(:required-flavors 

moving-object)) 

which allows relativity-mixins methods to access moving-object instance vari- 
ables such as mass (the rest mass), but does not specify any place for moving- 
object in the list of components. 

It is very common to specify the base flavor of a mixin with the 
•.required-flavors option in this way. 
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:included-flavors [Defflavor option] 

■ The arguments are names of flavors to be included in this flavor. The 
difference between declaring flavors here and declaring them at the top of 
the defflavor is that when component flavors are combined, if an included 
flavor is not specified as a normal component, it is inserted into the list of 
components immediately after the last component to include it. Thus 
included flavors act like defaults. The important thing is that if an 
included flavor is specified as a component, its position in the list of com- 
ponents is completely controlled by that specification, independently of 
where the flavor that includes it appears in the list. 

:included-flavors and ‘.required-flavors are used in similar ways; it would 
have been reasonable to use tincluded-flavors in the relativity-mixin example 
above. The difference is that when a flavor is required but not given as a hor- 
mal component, an error is signaled, but when a flavor is included but not 
given as a normal component, it is automatically inserted into the list of com- 
ponents at a reasonable place. 

:no-vanilla-flavor [Defflavor option] 

■ Normally when a flavor is instantiated, the special flavor si:vanilla- 
flavor is included automatically at the end of its list of components. The 
vanilla flavor provides some default methods for the standard operations 
which all objects are supposed to understand. These include ‘.print-self, 
‘.describe, :which-operations, and several other operations. 

□ If any component of a flavor specifies the :no-vanilla-flavor option, 
then si:vanilla-flavor is not included in that flavor. This option should not 
be used casually. 

’.default-handler [ Defflavor option] 

■ The argument is the name of a function that is to be called to handle 
any operation for which there is no method. Its arguments are the argu- 
ments of the send which invoked the operation, including the operation 
name as the first argument. Whatever values the default handler returns 
are the values of the operation. 

□ Default handlers can be inherited from component flavors. If a flavor 
has no other default handler, one is provided which signals an error if a 
message is sent for which there is no handler. 

tordered-instance-variables [Defflavor option] 

■ This option is mostly for esoteric internal system uses. The arguments 
are names of instance variables which must appear first (and in this order) 
in all instances of this flavor, or any flavor depending on this flavor. This 
is used for instance variables that are specially known about by other code 
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(e.g. non-LlSP) and also in connection with the : outside-accessible- 
instance-variables option. If the keyword is given alone, the arguments 
default to the list of instance variables given at the top of this defflavor. 

□ Any number of flavors to be combined together can specify this option. 
The longest ordered variable list applies, and an error is signaled if any of 
the other lists do not match its initial elements. 

□ Removing any of the :ordered-instance-variables, or changing their 
positions in the list, requires that you recompile all methods that use any 
of the affected instance variables. 

:outside-accessible-instance-variables [Defflavor option] 

■ The arguments are instance variables which are to be accessible from 
outside of this flavor’s methods. A macro is defined which takes an 
object of this flavor as an argument and returns the value of the instance 
variable; sett may be used to set the value of the instance variable. The 
name of the macro is the name of the flavor concatenated with a hyphen 
and the name of the instance variable. These macros are similar to the 
accessors created by defstruct. 

□ This feature works in two different ways, depending on whether or not 
the instance variable has been declared to have a fixed slot in all instances, 
via the :ordered-instance-variables option. 

□ If the variable is not ordered, the position of its value cell in the 
instance must be computed at run time. This takes noticeable time, possi- 
bly more or less than actually sending a message would take. An error is 
signaled if the argument to the accessor macro is not an instance or is an 
instance that does not have an instance variable with the appropriate 
name. However, there is no error check that the flavor of the instance is 
the flavor the accessor macro was defined for, or a flavor built upon that 
flavor. This error check would be too expensive. 

□ If the variable is ordered, the compiler compiles a call to the accessor 
macro into a primitive (actually a svref) which simply accesses that 
variable’s assigned slot by number. No error-checking is performed to 
make sure that the argument is really an instance, much less that it is of 
the appropriate type. 

□ sett works on these accessor macros to modify the instance variable. 

:accessor-prefix [Defflavor option] 

■ Normally the accessor macro created by the toutside-accessible- 
instance-variables option to access the flavor f’s instance variable v is 
named f-v. This option allows something other than the flavor name to be 
used for the first part of the macro name. Specifying (:accessor-prefix 
get$) causes it to be named get$v instead. 
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•.alias-flavor [Defflavor option] 

■ NOTE: :alias-flavor is presently unimplemented in Tek COMMON 
LISP. 

■ Marks this flavor as being an alias for another flavor. This flavor 
should have only one component, which is the flavor it is an alias for, and 
no instance variables or other options. No methods should be defined for 
it. 

□ The effect of the :alias-flavor option is that an attempt to instantiate 
this flavor actually produces an instance of the other flavor. Without this 
option, it would make an instance of this flavor, which might behave 
identically to an instance of the other flavor. :alias-flavor eliminates the 
need for separate mapping tables, method tables, etc. for this flavor, 
which becomes truly just another name for its component flavor. 

□ The alias flavor and its base flavor are also equivalent when used as an 
argument of subtypep or as the second argument of typep; however, if 
the alias status of a flavor is changed, you must recompile any code which 
uses it as the second argument to typep in order for such code to function. 

□ ; alias-flavor is mainly useful for changing a flavor’s name gracefully. 

abstract-flavor [Defflavor option] 

■ This option marks the flavor as one that is not supposed to be instan- 
tiated (that is, is supposed to be used only as a component of other fla- 
vors). An attempt to instantiate the flavor signals an error. 

□ It is sometimes useful to do compile-flavor-methods on a flavor that 
is not going to be instantiated, if the combined methods for this flavor will 
be inherited and shared by many others. :abstract-flavor tells compile- 
flavor-methods not to complain about missing required flavors, methods 
or instance variables. Presumably the flavors that depend on this one and 
actually are instantiated will supply what is lacking. 

■ NOTE: ; abstract-flavor is accepted but currently ignored in Tek COM- 
MON LISP. 

■.method-combination [Defflavor option] 

■ Specifies the method combination style to be used for certain opera- 
tions. Each argument to this option is a list (style order operation 1 opera- 
tion2 ...). operationl, operation2, etc. are names of operations whose 
methods are to be combined in the declared fashion, style is a keyword 
that specifies a style of combination, order is a keyword whose interpreta- 
tion is up to style; typically it is either :base-flavor-first or :base- 
flavor-last. 

□ Any component of a flavor may specify the type of method combina- 
tion to be used for a particular operation. If no component specifies a 
style of method combination, then the default style is used, namely 
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:daemon. 

If more than one component of a flavor specifies the combination style 
for a given operation, then they must agree on the specification, or else an 
error is signaled. 

:run-time-alternatives defflavor [ Defflavor option] 

mixture defflavor [Defflavor option] 

■ A run-time-alternative flavor defines a collection of similar flavors, all 
built on the same base flavor but having various mixins as well. Instantia- 
tion chooses a flavor of the collection at run time based on the init key- 
words specified, using an automatically generated instantiation flavor 
function. 

□ A simple example would be 

(defflavor foo () (basic-foo) 

(:run-time-alternatives 
(:big big-foo-mixin)) 

(:init-keywords :big)) 

□ Then (make-instance 'foo :big t) makes an instance of a flavor whose 
components are big-foo-mixin as well as foo. But (make-instance 'foo) or 
(make-instance 'foo :big nil) makes an instance of foo itself. The clause 
(:big big-foo-mixin) in the :run-time-alternatives says to incorporate big- 
foo-mixin if tbig’s value is t, but not if it is nil. 

□ There may be several clauses in the :run-time-alternatives. Each one 
is processed independently. Thus, two keywords :big and : wide could 
independently control two mixins, giving four possibilities. 

(defflavor foo () (basic-foo) 

(:run-time-alternatives (:big big-foo-mixin) 

(:wide wide-foo-mixin)) 

(:init-keywords :big)) 

□ It is possible to test for values other than t and nil. The clause: 

(:size (:big big-foo-mixin) 

(:small small-foo-mixin) 

(nil nil)) 

allows the value for the keyword :size to be :big, :small or nil (or omit- 
ted). If it is nil or omitted, no mixin is used (that’s what the second nil 
means). If it is :big or :small, an appropriate mixin is used. This kind of 
clause is distinguished from the simpler kind by having a list as its second 
element. The values to check for can be anything, but eq is used to com- 
pare them. 

□ The value of one keyword can control the interpretation of others by 
nesting clauses within clauses. If an alternative has more than two 
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elements, the additional elements are subclauses which are considered 
only if that alternative is selected. For example, the clause: 

(:ethereal (t ethereal-mixin) 

(nil nil 

(:size (:big big-foo-mixin) 

(:small small-foo-mixin) 

(nil nil)))) 

says to consider the :size keyword only if : ethereal is nil. 

□ .’mixture is synonymous with :run-time-alternatives. It exists for 
compatibility with Symbolics LISP or other LISP Machine systems. 

.* documentation [Defflavor option] 

■ Specifies the documentation string for the flavor definition. This docu- 
mentation can be viewed with the describe-flavor function. 


The following organization conventions are recommended for programs that 
use flavors. 

A base flavor is a flavor that defines a whole family of related flavors, all 
of which have that base flavor as a component. Typically the base flavor 
includes things relevant to the whole family, such as instance variables, 
•.required-methods and :required-instance-variables declarations, default 
methods for certain operations, ’.method-combination declarations, and docu- 
mentation on the general protocols and conventions of the family. Some base 
flavors are complete and can be instantiated, but most cannot be instantiated 
themselves. They serve as a base upon which to build other flavors. The base 
flavor for the foo family is often named basic-foo. 

A mixin flavor is a flavor that defines one particular feature of an object. 
A mixin cannot be instantiated, because it is not a complete description. Each 
module or feature of a program is defined as a separate mixin; a usable flavor 
can be constructed by choosing the mixins for the desired characteristics and 
combining them, along with the appropriate base flavor. By organizing your 
flavors this way, you keep separate features in separate flavors, and you can 
pick and choose among them. Sometimes the order of combining mixins does 
not matter, but often it does, because the order of flavor combination controls 
the order in which daemons are invoked and wrappers are wrapped. Such order 
dependencies should be documented as part of the conventions of the appropri- 
ate family of flavors. A mixin flavor that provides the mumble feature is often 
named mumble-mixin. 

If you are writing a program that uses someone else’s facility, using that 
facility’s flavors and methods, your program may still define its own flavors, in 
a simple way. The facility provides a base flavor and a set of mixins: the caller 
can combine these in various ways depending on exactly what it wants, since 
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the facility probably does not provide all possible useful combinations. Even if 
your private flavor has exactly the same components as a pre-existing flavor, it 
can still be useful since you can use its :default-init-plist to select options of 
its component flavors and you can define one or two methods to customize it 
just a little. 


6.10 

Vanilla flavor 

sitvanilla-flavor [Flavor] 

■ NOTE: For source code compatibility with other implementations, Tek 
COMMON lisp defines si: as an alias for the system: package. 

■ Unless you specify otherwise (with the :no-vanilla-flavor option to 
defflavor), every flavor includes the vanilla flavor, which has no instance 
variables but provides some basic useful methods. 

•.print-self stream prindepth escape-p [Message] 

■ The object should output its printed-representation to a stream. The 
printer sends this message when it encounters an instance or an entity. 
The arguments are the stream, the current depth in list-structure (for com- 
parison with *print-level *), and whether escaping is enabled (a copy of 
the value of *print-escape*). sirvanilla-flavor ignores the last two argu- 
ments and prints something like #<flavor-name octal-address>. The 
flavor-name tells you what type of object it is and the octal-address 
allows you to tell different objects apart. 

’.describe [Message] 

■ The object should describe itself, printing a description onto the stan- 
dard output stream. The describe function sends this message when it 
encounters an instance. si:vanilla-flavor outputs in a reasonable format the 
object, the name of its flavor, and the names and values of its instance- 
variables. The instance variables are printed in their order within the 
instance. 

:which-operations [Message] 

■ The object should return a list of the operations it can handle, 
s'r.vanilla-flavor generates the list once per flavor and remembers it, 
minimizing consing and compute-time. If the set of operations handled is 
changed, this list is regenerated the next time someone asks for it. 


The operations described in this section are a standard protocol, which all 
message-receiving objects are assumed to understand. The standard methods 
that implement this protocol are automatically supplied by the flavor system 
unless the user specifically tells it not to do so. These methods are associated 
with the flavor sirvanilla-flavor: 
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:operation-handled-p operation [Message] 

■ operation is an operation name. The object should return t if it has a 
handler for the specified operation, nil if it does not. 

:get-handler-for operation [Message] 

■ operation is an operation name. The object should return the method it 
uses to handle operation. If it has no handler for that operation, it should 
return nil. This is like the get-handler-for function. 

:send-if-handles operation arguments* [Message] 

■ operation is an operation name and arguments is a list of arguments for 
the operation. If the object handles the operation, it should send itself a 
message with that operation and arguments, and return whatever values 
that message returns. If it doesn’t handle the operation it should just 
return nil. 

:eval-inside-yourself form [Message] 

■ The argument is a form that is evaluated in an environment in which 
special variables with the names of the instance variables are bound to the 
values of the instance variables. It works to setq one of these special 
variables; the instance variable is modified. This is intended to be used 
mainly for debugging. 

:funcall-inside-yourself function &rest args [Message] 

■ function is applied to args in an environment in which special variables 
with the names of the instance variables are bound to the values of the 
instance variables. It works to setq one of these special variables; the 
instance variable is modified. This is a way of allowing callers to provide 
actions to be performed in an environment set up by the instance. 

’.break [Message] 

■ break is called in an environment in which special variables with the 
names of the instance variables are bound to the values of the instance 
variables. 


When a flavor has or inherits more than one method for an operation, they must 
be called in a specific sequence. The flavor system creates a function called a 
combined method which calls all the user-specified methods in the proper 
order. Invocation of the operation actually calls the combined method, which 
is responsible for calling the others. 


6.11 

Method 

combination 
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For example, if the flavor foo has components and methods as follows: 

(defflavor foo () (foo-mixin foo-base)) 

(defflavor foo-mixin () (bar-mixin)) 

(defmethod (foo :before :hack) ...) 

(defmethod (foo :after :hack) ...) 

(defmethod (foo-mixin '.before rhack) ...) 

(defmethod (foo-mixin rafter :hack) ...) 

(defmethod (bar-mixin rbefore :hack) ...) 

(defmethod (bar-mixin :hack) ...) 

(defmethod (foo-base :hack) ...) 

(defmethod (foo-base rafter rhack) ...) 

then the combined method generated looks like this (ignoring many details not 
related to this issue): 

(defmethod (foo rcombined rhack) (&rest args) 

(apply #’(:method foo .-before rhack) args) 

(apply #’(:method foo-mixin rbefore rhack) args) 

(apply #’(:method bar-mixin rbefore rhack) args) 

(multiple-value-prog 1 

(apply #’(:method bar-mixin rhack) args) 

(apply #’(:method foo-base rafter rhack) args) 

(apply #’(:method foo-mixin rafter rhack) args) 

(apply #’(:method foo rafter rhack) args))) 

This example shows the default style of method combination, the one described 
in the introductory parts of this chapter, called ; daemon combination. Each 
style of method combination defines which method types it allows, and what 
they mean. : daemon combination accepts method types ’.before and :after, 
in addition to untyped methods; then it creates a combined method which calls 
all the ‘.before methods, only one of the untyped methods, and then all the 
’.after methods, returning the value of the untyped method. The combined 
method is constructed by a function much like a macro’s expander function, 
and the precise technique used to create the combined method is what gives 
’.before and ’.after their meaning. 

Note that the ’.before methods are called in the order foo, foo-mixin, bar- 
mixin and foo-base. (foo-base does not have a ’.before method, but if it had 
one that one would be last.) This is the standard ordering of the components of 
the flavor foo; since it puts the base flavor last, it is called :base-flavor-last 
ordering. The '.after methods are called in the opposite order, in which the 
base flavor comes first. This is called :base-flavor-first ordering. 
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Only one of the untyped methods is used; it is the one that comes first in 
:base-flavor-last ordering. An untyped method used in this way is called a 
primary method. 

Other styles of method combination define their own method types and 
have their own ways of combining them. Use of another style of method com- 
bination is requested with the :method-combination option to defflavor. 
Here is an example which uses :list method combination, a style of combina- 
tion that allows :list methods and untyped methods: 

(defflavor foo () (foo-mixin foo-base)) 

(defflavor foo-mixin () (bar-mixin)) 

(defflavor foo-base () () 

(method-combination (:list :base-flavor-!ast :win))) 

(defmethod (foo :list :win) ...) 

(defmethod (foo :win) ...) 

(defmethod (foo-mixin :list :win) ...) 

(defmethod (bar-mixin :list :win) ...) 

(defmethod (bar-mixin win) ...) 

(defmethod (foo-base :win) ...) 

;; yielding this combined method 

(defmethod (foo rcombined :win) (&rest args) 

(list (apply #’(:method foo :list win) args) 

(apply #’(:method foo-mixin :list win) args) 

(apply #’(:method bar-mixin :list win) args) 

(apply #’(:method foo win) args) 

(apply #’(:method bar-mixin win) args) 

(apply #’(:method foo-base win) args))) 

The ; method-combination option in the defflavor for foo-base causes :list 
method combination to be used for the :win operation on all flavors that have 
foo-base as a component, including foo. The result is a combined method 
which calls all the methods, including all the untyped methods rather than just 
one, and makes a list of the values they return. All the :list methods are called 
first, followed by all the untyped methods; and within each type, the ".base- 
flavor-last ordering is used as specified. If the :method-combination option 
said :base-flavor-first, the relative order of the -.list methods would be 
reversed, and so would the untyped methods, but the ".list methods would still 
be called before the untyped ones. :base-flavor-last is more often right, since 
it means that foo’s own methods are called first and si:vanilla-flavor’s methods 
(if it has any) are called last. 
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One method type, ; default , has a standard meaning independent of the 
style of method combination, and can be used with any style. 

Here are the standardly defined method combination styles: 

'.daemon [Method-combination type] 

■ The default style of method combination. All the ‘.before methods are 
called, then the primary (untyped) method for the outermost flavor that 
has one is called, then all the ’.after methods are called. The value 
returned is the value of the primary method. 

:daemon-with-or [Method-combination type] 

■ Like the '.daemon method combination style, except that the primary 
method is wrapped in an tor special form with all tor methods. Multiple 
values can be returned from the primary method, but not from the tor 
methods (as in the or special form). This produces combined methods 
like the following: 

(progn 

(foo-before-method) 

(multiple-value-prog 1 
(or (foo-or-method) 

(foo-primary-method)) 

(foo-after-method))) 

This is useful primarily for flavors in which a mixin introduces an alterna- 
tive to the primary method. Each tor method gets a chance to run before 
the primary method and to decide whether the primary method should be 
run or not; if any tor method returns a non -nil value, the primary method 
is not run (nor are the rest of the tor methods). Note that the ordering of 
the combination of the tor methods is controlled by the order keyword in 
the '.method-combination option. 

tdaemon-with-and [Method-combination type] 

■ Like tdaemon-with-or except that it combines '.and methods in an 
and special form. The primary method is run only if all of the tand 
methods return non-nil values. 

tdaemon-with-override [Method-combination type] 

■ Like the '.daemon method combination style, except an or special 
form is wrapped around the entire combined method with all '.override 
typed methods before the combined method. This differs from tdaemon- 
with-or in that the ‘.before and tafter daemons are run only if none of the 
'.override methods returns non-nil. The combined method looks some- 
thing like this: 
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(or (foo-override-method) 
(progn 

(foo-before-method) 
(multiple-value-prog 1 
(foo-primary-method) 
(foo-after-method)))) 


: progn [Method-combination type] 

■ Calls all the methods inside a progn special form. Only untyped and 
tprogn methods are allowed. The combined method calls all the tprogn 
methods and then all the untyped methods. The result of the combined 
method is whatever the last of the methods returns. 

tor [Method-combination type ] 

■ Calls all the methods inside an or special form. This means that each 
of the methods is called in turn. Only untyped methods and tor methods 
are allowed; the tor methods are called first. If a method returns a non - nil 
value, that value is returned and none of the rest of the methods are called; 
otherwise, the next method is called. In other words, each method is 
given a chance to handle the message; if it doesn’t want to handle the 
message, it can return nil, and the next method gets a chance to try. 

tand [Method-combination type] 

■ Calls all the methods inside an and special form. Only untyped 
methods and tand methods are allowed. The basic idea is much like tor ; 
see above. 

’.append [Method-combination type] 

■ Calls all the methods and appends the values together. Only untyped 
methods and ‘.append methods are allowed; the tappend methods are 
called first. 

tnconc [Method-combination type] 

■ Calls all the methods and nconcs the values together. Only untyped 
methods and tnconc methods are allowed, etc. 


tlist [ Method-combination type] 

■ Calls all the methods and returns a list of their returned values. Only 
untyped methods and ’.list methods are allowed, etc. 
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:inverse-list [Method-combination type] 

■ Calls each method with one argument; these arguments are successive 
elements of the list that is the sole argument to the operation. Returns no 
particular value. Only untyped methods and :inverse-list methods are 
allowed, etc. 

□ If the result of a ://sf-combined operation is sent back with an 
;/nverse-//'sf-combined operation, with the same ordering and with 
corresponding method definitions, each component flavor receives the 
value that came from that flavor. 

:pass-on [Method-combination type] 

■ NOTE: :pass-on method combination is not yet implemented in Tek 
Common Lisp. 

■ Calls each method on the values returned by the preceding one. The 
values returned by the combined method are those of the outermost call. 
The format of the declaration in the defflavor is: 

(:method-combination 
(:pass-on (ordering . argiist) 
operation-names)) 

where ordering is tbase-flavor-first or :base-flavor-last. argiist may 
include the &aux and &optional keywords. 

□ Only untyped methods and :pass-on methods are allowed. The 
tpass-on methods are called first. 

tease [Method-combination type] 

■ With tease method combination, the combined method automatically 
does a caseq dispatch on the first argument of the operation, known as 
the suboperation. Methods of type tease can be used, and each one 
specifies one suboperation that it applies to. If no tease method matches 
the suboperation, the primary method, if any, is called. 

(defflavor foo (a b) () 

(:method-combination (:case :base-flavor-last :win))) 

(defmethod (foo :case :win :a) () 

;; This method handles (send a-foo :win :a): 

a) 

(defmethod (foo :case :win :a*b) () 

;; This method handles (send a-foo :win :a*b): 

(* a b)) 

(defmethod (foo :win) (suboperation) 
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;; This method handles 

;; (send a-foo :win :something-else): 

(list ’something-random suboperation)) 

:case methods are unusual in that one flavor can have many :case 
methods for the same operation, as long as they are for different subopera- 
tions. 

□ The suboperations :which-operations, :operation-handled-p , 
:send-if-handles and :get-handler-for are all handled automatically 
based on the collection of :case methods that are present. 

■ NOTE: :send-if-handles and :get-handler-for are presently unimple- 
mented in Tek COMMON LISP. 

□ Methods of type :or are also allowed. They are called just before the 
primary method, and if one of them returns a non- nil value, that is the 
value of the operation, and no more methods are called. 

Here is a list of all the method types recognized by the standard styles of 
method combination: 

no method type [Method type] 

■ If no type is given to defmethod, a primary method is created. 
This is the most common type of method. 

: before [ Method type] 

: after [ Method type] 

■ These are used for the before-daemon and after-daemon methods 
used by tdaemon method combination. 

; default [Method type] 

■ If there are no untyped methods among any of the flavors being 
combined, then the ; default methods (if any) are treated as if they 
were untyped. If there are any untyped methods, the ‘.default 
methods are ignored. 

□ Typically a base-flavor defines some default methods for certain 
of the operations understood by its family. When using the default 
kind of method combination these default methods are suppressed if 
another component provides a primary method. 


tor 
tand 

■ These are used for :daemon-with-or and :daemon-with-and 
method combination. The tor methods are wrapped in an or, or the 
tand methods are wrapped in an and, together with the primary 


[Method type] 
[Method type] 


- 86 ) 



Tektronix, Inc. 
6-42 Flavors 


method, between the ‘.before and ‘.after methods. 

’.override [Method type] 

■ Allows the features of :or method combination to be used 
together with daemons. If you specify :daemon-with-override 
method combination, you may use ’.override methods. The /over* 
ride methods are executed first, until one of them returns non- nil. If 
this happens, that method’s value(s) are returned and no more 
methods are used. If all the ‘.override methods return nil, the 
-.before, primary and ‘.after methods are executed as usual. 

□ In typical usages of this feature, the ‘.override method usually 
returns nil and does nothing, but in exceptional circumstances it takes 
over the handling of the operation. 


tor 

tand 

tprogn 

tlist 

tinve rse-list 
:pass-on 
‘.append 
tnconc 


[ Method type] 
[ Method type] 
[ Method type] 
[Method type ] 
[Method type] 
[Method type] 
[Method type] 
[Method type] 


■ Each of these methods types is allowed in the method combina- 
tion style of the same name. In those method combination styles, 
these typed methods work just like untyped ones, but all the typed 
methods are called before all the untyped ones. These method types 
can be used with any method combination style; they have standard 
meanings independent of the method combination style being used. 


twrapper [Method type] 

■ This is used internally by defwrapper. 

‘.combined [Method type] 

■ This is used internally for automatically-generated combined 
methods. 


The most common form of combination is ‘.daemon. One thing may not be 
clear: when do you use a ’.before daemon and when do you use an ‘.after 
daemon? In some cases the primary method performs a clearly-defined action 
and the choice is obvious: ‘.before tiaunch-rocket puts in the fuel, and tafter 
•Jaunch-rocket turns on the radar tracking. 

In other cases the choice can be less obvious. Consider the tinit message, 
which is sent to a newly-created object. To decide what kind of daemon to use. 
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we observe the order in which daemon methods are called. First the .'before 
daemon of the instantiated flavor is called, then .'before daemons of succes- 
sively more basic flavors are called, and finally the :before daemon (if any) of 
the base flavor is called. Then the primary method is called. After that, the 
:after daemon for the base flavor is called, followed by the '.after daemons at 
successively less basic flavors. 

Now, if there is no interaction among all these methods, if their actions 
are completely independent, then it doesn’t matter whether you use a : before 
daemon or an ‘.after daemon. There is a difference if there is some interaction. 
The interaction we are talking about is usually done through instance variables; 
in general, instance variables are how the methods of different component fla- 
vors communicate with each other. In the case of the :init operation, the init- 
plist can be used as well. The important thing to remember is that no method 
knows beforehand which other flavors have been mixed in to form this flavor; 
a method cannot make any assumptions about how this flavor has been com- 
bined, and in what order the various components are mixed. 

This means that when a '.before daemon has run, it must assume that none 
of the methods for this operation have run yet. But the '.after daemon knows 
that the '.before daemon for each of the other flavors has run. So if one flavor 
wants to convey information to the other, the first one should transmit the 
information in a ‘.before daemon, and the second one should receive it in an 
‘.after daemon. So while the '.before daemons are run, information is transmit- 
ted-, that is, instance variables get set up. Then, when the '.after daemons are 
run, they can look at the instance variables and act on their values. 

In the case of the tinit method, the ‘.before daemons typically set up 
instance variables of the object based on the init-plist, while the ’.after daemons 
actually do things, relying on the fact that all of the instance variables have 
been initialized by the time they are called. 

The problems become most difficult when you are creating a network of 
instances of various flavors that are supposed to point to each other. For exam- 
ple, suppose you have flavors for buffers and streams, and each buffer should 
be accompanied by a stream. If you create the stream in the ‘.before :init 
method for buffers, you can inform the stream of its corresponding buffer with 
an init keyword, but the stream may try sending messages back to the buffer, 
which is not yet ready to be used. If you create the stream in the '.after :init 
method for buffers, there will be no problem with stream creation, but some 
other ‘.after tinit methods of other mixins may have run and made the assump- 
tion that there is to be no stream. The only way to guarantee success is to 
create the stream in a '.before method and inform it of its associated buffer by 
sending it a message from the buffer’s ‘.after :init method. This scheme — 
creating associated objects in '.before methods but linking them up in tatter 
methods — often avoids problems, because all the various associated objects 
used by various mixins at least exist when it is time to make other objects point 
to them. 
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6.12 

Implementing 

flavors 


Since flavors are not hierarchically organized, the notion of levels of 
abstraction is not rigidly applicable. However, it remains a useful way of 
thinking about systems. 

An object that is an instance of a flavor is implemented as a hidden data type 
similar to a simple vector. The zeroth slot points to a flavor descriptor, and 
successive slots of the vector store the instance variables. Sometimes, for 
debugging, it is useful to know that svref is legal on an instance. However, it is 
of course a violation of the implicit contract with a flavor to use this fact in real 
code. 

A flavor descriptor is a defstruct of type flavors::flavor. It is also stored on 
the flavors::flavor property of the flavor name. It contains, among other things, 
the name of the flavor, the size of an instance, the table of methods for han- 
dling operations, and information for accessing the instance variables. The 
function (describe-flavor flavor-name) will print much of this information in 
readable format, defflavor creates a. flavor-descriptor for each flavor and links 
them together according to the dependency relationships between flavors. 
Much of the information stored there, of course, is not computed until flavor- 
combination time. 

A message is sent to an instance simply by calling it as a function, with 
the first argument being the operation. The evaluator looks up the operation in 
the dispatch hashtable stored in the flavor descriptor for that flavor and obtains 
a handler function and a mapping table. It then binds self to the object, 
si::self-mapping-table to the mapping table. Finally, the handler function is 
called. If there is only one method to be invoked, the handler function is that 
method; otherwise it is an automatically-generated function, called the com- 
bined method, which calls the component methods appropriately. If there are 
wrappers, they are incorporated into the combined method. 

The code body of each method function knows only about the instance 
variables declared for its flavor, and this set of instance variables is known 
when the defining defmethod is evaluated. However, the location of these 
instance variables within an instance of an arbitrary flavor containing that fla- 
vor is not known until flavor-combination time. The mapping table is used by 
a method to map the set of instance variables it knows about into slot offsets 
within self. If all the component methods invoked by the combined method 
derive from a single flavor, the mapping table obtained from the method 
dispatch hashtable is a simple vector of slot numbers. If methods from more 
than one component flavor are invoked from the combined method, then the 
mapping table is an alist mapping each component flavor to its appropriate 
component mapping table, and the combined method takes care of binding 
si:self-mapping-table appropriately before calling each component. 

For both interpreted and compiled methods in Tek COMMON LISP all 
instance variables are lexical scoped within the body of the method. (This is 
different from the FRANZ LISP implementation, in which the interpreter cannot 
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implement lexical scoping.) 


There is a certain amount of freedom to the order in which you do defflavors, 
defmethods, and defwrappers. This freedom is designed to make it easy to 
load programs containing complex flavor structures without having to do 
things in a certain order. It is considered important that not all the methods for 
a flavor need be defined in the same file. Thus the partitioning of a program 
into files can be along modular lines. 

The rules for the order of definition are as follows. 

Before a method can be defined (with defmethod or defwrapper) its fla- 
vor must have been defined (with defflavor). This makes sense because the 
system has to have a place to remember the method, and because it has to know 
the instance-variables of the flavor if the method is to be compiled. 

When a flavor is defined (with defflavor) it is not necessary that all of its 
component flavors be defined already. This is to allow defflavors to be spread 
between files according to the modularity of a program, and to provide for 
mutually-dependent flavors. Methods can be defined for a flavor some of 
whose component flavors are not yet defined; however, compilation of a 
method which refers to instance variables inherited from a flavor not yet 
defined, and not mentioned in a :requi red-instance-variable clause, will pro- 
duce a compiler warning that the variable was declared special (because the 
system did not realize it was an instance variable). If this happens, you should 
fix the problem and recompile. It may be sufficient just to change the order in 
which the flavors are defined, but considerations of modularity, clarity, and self 
documentation make it far preferable to insert irequired-instance-variable 
clauses. 

The methods automatically generated by the igettable-instance- 
variables, :settable-instance-variables, and :outside-accessible- 
instance-variables defflavor options are generated at the time the defflavor 
is done. 

The first time a flavor is instantiated, or when compile-flavor-methods is 
done, the system looks through all of the component flavors and gathers vari- 
ous information. At this point an error is signaled if not all of the components 
have been defflavored. This is also the time at which certain other errors are 
detected, such as the lack of a required instance-variable (see the : required - 
instance-variables option to defflavor). The ordered set of instance variables 
is determined and their slots assigned within an instance. The combined 
methods are generated unless they already exist and are correct. The flavor 
system tries very hard never to redefun a combined method unless its contents 
actually must change. 

After a flavor has been instantiated, it is possible to make changes to it. 
Such changes affect all existing instances if possible. This is described more 
fully immediately below. 


6.12.1 
Order of 
definition 


86 ) 



Tektronix, Inc. 
6-46 Flavors 


6.12.2 
Changing a 
flavor 


6.13 

Property list 
operations 


You can change anything about a flavor at any time. You can change the 
flavor’s general attributes by doing another defflavor with the same name. 
You can add or modify methods by doing defmethods. If you do a def- 
method with the same flavor-name, operation (and suboperation if any), and 
(optional) method-type as an existing method, that method is replaced by the 
new definition. 

These changes always propagate to all flavors that depend upon the 
changed flavor. Normally the system propagates the changes to all existing 
instances of the changed flavor and its dependent flavors. However, this is not 
possible when the flavor has been changed in such a way that the old instances 
would not work properly with the new flavor. This happens if you change the 
number of instance variables, which changes the size of an instance. It also 
happens if you change the order of the instance variables (and hence the 
storage layout of an instance), or if you change the component flavors (which 
can change several subtle aspects of an instance). The system does not keep a 
list of all the instances of each flavor, so it cannot find the instances and 
modify them to conform to the new flavor definition. Instead it gives you a 
warning message to the effect that the flavor was changed incompatibly and the 
old instances will not get the new version. The system leaves the old flavor 
data-structure intact (the old instances continue to point at it) and makes a new 
one to contain the new version of the flavor. If a less drastic change is made, 
the system modifies the original flavor data-structure, thus affecting the old 
instances that point at it. However, if you redefine methods in such a way that 
they only work for the new version of the flavor, then trying to use those 
methods with the old instances won’t work. 


It is often useful to associate a property list with an abstract object, for the 
same reasons that it is useful to have a property list associated with a symbol. 
This section describes a mixin flavor, si:property-list-mixin, that can be used as 
a component of any new flavor in order to provide that new flavor with a pro- 
perty list. For more details and examples, see the general discussion of pro- 
perty lists. The usual property list functionalities (get, putprop, etc.) are 
obtained by sending the instance the corresponding message. The contents of 
the property list can be initialized by providing a ; property-list init option on 
the init-plist given to instantiate-flavor. 

si:property-list-m ixin [ Flavor] 

■ This mixin flavor provides the basic operations on property lists. 


:get property-name 

■ Looks up the object’s property-name property. 


[Message] 
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:getl property-name-list [ Message ] 

■ Like the :get operation, except that the argument is a list of property 
names. The :getl operation searches down the property list until it finds a 
property whose property name is one of the elements of property-name- 
list. It returns the portion of the property list beginning with the first such 
property that it found. If it doesn’t find any, it returns nil. 

:putprop value property-name [ Message ] 

■ Gives the object a property-name property of value. 

:remprop property-name [Message] 

■ Removes the object’s property-name property, by splicing it out of the 
property list. It returns one of the cells spliced out, whose car is the 
former value of the property that was just removed. If there was no such 
property to begin with, the value is nil. 

:push-propertyva\ueproperty-name [Message] 

■ The property-name property of the object should be a list (note that nil 
is a list and an absent property is nil). This operation sets the property- 
name property of the object to a list whose car is value and whose cdr is 
the former property-name property of the list. This is analogous to doing 

(push value (get object property-name)) 

’.property-list [Message] 

■ RETURNS the list of alternating property names and values that imple- 

ments the property list. 

:set-property-list list [Message] 

■ Sets the list of alternating property names and values that implements 
the property list to list. 


There are no built-in techniques to copy instances because there are too many 
questions raised about what should be copied. These include: 

• Do you or do you not send an :init message to the new instance? If you 
do, what init-plist options do you supply? 

• If the instance has a property list, you should copy the property list (e.g. 
with copylist) so that putprop or remprop on one of the instances does 
not affect the properties of the other instance. 

• If the instance is a port connected to a network, some of the instance vari- 
ables represent an agent in another host elsewhere in the network. Should 
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the copy talk to the same agent, or should a new agent be constructed for 
it? 

• If the instance is a port connected to a file, should copying the stream 
make a copy of the file or should it make another stream open to the same 
file? Should the choice depend on whether the file is open for input or for 
output? 

In general, you can see that in order to copy an instance one must understand a 
lot about the instance. One must know what the instance variables mean so 
that the values of the instance variables can be copied if necessary. One must 
understand what relations to the external environment the instance has so that 
new relations can be established for the new instance. One must even under- 
stand what the general concept ‘copy’ means in the context of this particular 
instance, and whether it means anything at all. 

Copying is a generic operation, whose implementation for a particular 
instance depends on detailed knowledge relating to that instance. Modularity 
dictates that this knowledge be contained in the instance’s flavor, not in a 
general copying function. Thus the way to copy an instance is to send it a 
message, as in (send object :copy). It is up to you to implement the operation 
in a suitable fashion, such as 

(defflavor too (a b c) () 

(-.initable-instance-variables a b)) 

(defmethod (too ropy) () 

(make-instance ’too :a a :b b)) 

The flavor system chooses not to provide any default method for copying 
an instance, and does not even suggest a standard name for the copying 
message, because copying involves so many semantic issues. 

If a flavor supports the :reconstruction-init-plist operation, a suitable 
copy can be made by invoking this operation and passing the result to make- 
instance along with the flavor name. This is because the definition of what 
the :reconstruction-init-plist operation should do requires it to address all the 
problems listed above. Implementing this operation is up to you, and so is 
making sure that the flavor implements sufficient init keywords to transmit any 
information that is to be copied. 
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In order to speed up a large LISP program it is first necessary to determine the 
parts of the program where most of the time is being spent. Tek COMMON LISP 
automatically counts the number of times each function is called. This infor- 
mation, along with the programmer’s knowledge of which functions are large 
and/or time consuming, will pinpoint the parts of the program that should be 
optimized. 

The code for recording function call counts is very small and fast (just one 
machine instruction per function call) thus for most applications it makes sense 
to permit function call counting to occur. However for certain time critical 
highly recursive functions, it may be desireable to instruct the compiler to omit 
the the function call counting code for certain functions. This can be done by 
setting the variable compiler:*do-call-counts* to nil before compiling the func- 
tion. Or the variable compiler:generate-ca!l-count-switch can be modified so 
call counts are generated depending on user settings of speed and safety. See 
§2.4.2, Declarations and optimizations under The compiler. The code which 
does the counting is compiled into the compiled functions and thus can be 
turned on or off on a function by function basis. The system code always does 
call counting. All the profiling functions are exported from excl package. (See 
Chapter 9.) 

excl:function-call-report Aoptional number-to-report [Function] 

■ For all interned symbols with compiled function definitions, gather 
information on the number of times they have been called since the last 
function call report, and clear the call counts at the same time. Then sort 
the functions in descending order of number of times called and print the 
function call information on the most called functions. The optional argu- 
ment, number-to-report, determines how many functions are printed, 
number-to-report defaults to 50. Functions which are anonymous (not 
associated with any interned symbol) will be omitted from this list. 

excl:function-call-list [Function] 

■ This function returns a list of all the functions which were called at 
least once and their call counts, and it clears the call counts. The form of 
each list entry is (number-of-calls . function-name). The list is sorted in 
descending order of number-of-calls. 
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excl:function-call-clear [Function] 

■ Clear the call counts for all functions. 

exckf unction-call-count function [Function] 

■ Return the number of times function has been called, function can 
either be a compiled function object or a symbol with a compiled function 
object as its function definition. 

excl:get-and-zero-call-count function [Function] 

■ Return the number of times the function has been called and zero the 
call count, function can either be a compiled function object or a symbol 
with a compiled function object as its function definition. 

compiler:*do-call-counts* [Variable] 

■ If non -nil, then when the compiler compiles a function it will add code 
to maintain a call count. 
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8 Foreign functions 


The foreign-function interface allows one to dynamically load compiled 
foreign code into a running LISP. Foreign code is defined to be code written in 
C The foreign-function interface allows users to load compiled code written in 
a foreign language into a running LISP, execute it from within LISP, call LISP 
functions from within the foreign code, return to LISP and pass data back and 
forth between LISP and the foreign code. 

This mechanism is very powerful, as programs need not be recoded into 
LISP to use them. Another advantage arises during program development. For 
example, a large graphics library can be loaded into LISP and all the functions 
will be accessible interactively. This enables rapid prototyping of systems that 
use the library functions, since the powerful LISP debugging and development 
environment is now available. 

The foreign code may be in either relocatable object (.r) files or in 
libraries made with the libgen command. Any one such file may contain many 
foreign functions or procedures. This chapter describes all aspects of the 
foreign-function interface. Sections 8.1 and 8.2 document the dynamic loader 
that adds foreign code into a running LISP. Sections 8.3 through 8.5 describe 
how to call foreign functions from within LISP. Section 8.6 explains how to 
handle signals in C code called by LISP. Sections 8.7 and 8.8 describe how to 
call back to LISP functions from foreign code. Section 8.9 documents the 
cstructs facility for defining C structures in LISP. 

The interface currently supports only C. The foreign-function interface in 
LISP is in the package foreign-functions, nicknamed ff. (Note that you must 
either use the package qualifier ff: before foreign-function interface symbols, or 
‘use’ the package 

(use-package ’ff) 
before using the interface. 

It is important to note that the foreign-function interface was designed for 
the C compilers on the system at the time of the release of this version of Tek 
COMMON LISP. New versions of the C compilers may, for purposes of using 
the foreign-function interface, be incompatible with the version current when 
the interface was written. In that case, it is possible that already written and 
compiled LISP code may cease to work, and that, for a time, the interface may 
fail altogether. Tektronix will maintain the foreign-function interface, and 
make it compatible with each new release of the system compilers. We cannot 
guarantee, however, that already compiled code will continue to work in the 
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8.1 

Loading 
foreign code 


8.1.1 

The loader 


presence of changes in the C compilers. 


LISP uses the operating system loader to load files containing compiled foreign 
code and/or libraries. Any one file may contain many foreign functions or pro- 
cedures. Once a piece of foreign code has been loaded into the running LISP 
process, it need never be loaded again. 


Foreign code is loaded in by the function load. If there is only one file to be 
loaded with a .r extension, then you use load in the same way it is used to load 
LISP files. There are two added keywords for multiple files or for libraries. 

load filename &key ’.foreign-files tsystem-libraries [Function] 

■ If load succeeds, the return value is t. If load fails, the return value is 
nil. Reasons for the loader to fail include an incorrect file name, or an 
external reference multiply defined in one or more of the files and in the 
LISP symbol table. Loader error messages are output to standard output. 

’.foreign-files ( extra-file+ ) [Keyword] 

■ This keyword specifies a list of names of additional files. The - 
filename argument to the load function and each extra-file are han- 
dled slightly differently (for unavoidable system reasons). The - 
filename argument is converted to a pathname, and merged with each 
element of the search list system :*load-search-list* until a file is 
located. This is identical to what the load function does with LISP 
files. However, each extra-file specified with the ’.foreign-files key- 
word is not handled this way — each name is passed on to the loader 
verbatim. The loader executes in the current directory, therefore 
each extra-file will be interpreted relative to the current directory 
(which need not be in the load search list). 

□ If there are several files, they can all be included in the list speci- 
fied by the ’.foreign-files keyword, but then the initial argument to 
load must be the empty string 

; system-libraries ( library+ ) [Keyword] 

■ This keyword specifies the system libraries. By default this list of 
libraries always contains the C run-time library, so do not specify this 
library. Loaders usually use an abbreviation for system libraries; you 
must use the same abbreviation. See the Id command in the Unix 
User’s Manual for an explanation of the system libraries and their 
abbreviations. For example, the abbreviation for the math library is 
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mathlib so to include this library, you include m in the library list. 

□ For example, if you have two files /usr/mymod2.r and mymodl.r, 
which use a graphics library, mylib and the system math library, load 
this foreign code into LISP using: 

(load "mymodl .r ” 

:foreign-files ’("/usr/mymod2.r” "+lmylib") 
isystem-libraries ’("mathlib")) 

□ Note that mylib will be searched for unresolved entry points 
before the math library. The loader searches the libraries for 
unresolved external references found in the .r files and does not load 
any other code from the libraries. 


To load a library function, one need only make a .r file with the function refer- 
ence and load it. Here is an example. 

Say you wish to load the system function crypt(), found in the standard C 
library. Create a C file (say cnames.c) containing the following. 


dummy () /* The dummy function does not */ 

/* do anything except contain */ 

/* the reference to the C library */ 
/* function crypt */ 

{ 

crypt(); /* refer to crypt */ 

} 


8.1.2 

Loading 

library 

functions 


Compile it to cnames.r and load this file into LISP using 
(load "cnames.o") 

Since the C run-time library is searched automatically, it is not specified. (See 
the Unix User’s Manual for the functions available in the C run-time library). 


The most common load error arises when the foreign code has an entry point 8.2 

name duplicating one already present in LISP. The entry point name must be Load errors 
removed before the foreign code will successfully load. => While each foreign 
function name corresponds to an entry point name, a foreign function with the 
same name as a LISP function name causes no name conflict. 

Entry point names are usually system dependent variations on the name of 
the function in the foreign source code. On the Tektronix, C externals and func- 
tion names are turned into entry point names by prepending an underscore, the 
following function produces the correct entry point name. 
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ff:convert-to-lang string &key language [Function] 

■ This function takes the string arguments and returns a string of the 
correct form for the system. The keyword language is either :c or :for- 
tran, with the default being :c. 

Remove name conflicts between foreign entry points and LISP internal 
entry points with the utility function 

ff:remove-entry-point name-of-entry-point [Function] 

■ This function removes the entry point name in a running LISP. It 
returns f if it successfully finds and removes the entry point name, other- 
wise it returns nil. 

For example, suppose you have a foreign function named curpgmname. As it 
happens, a C function named curpgmname is loaded with the initial LISP sys- 
tem. All references to that curpgmname in already loaded code have already 
been resolved into absolute addresses, so removing the entry point will not 
affect that code. (Code loaded after removing the entry point will not, how- 
ever, find the original curpgmname.) Prior to loading in your foreign code, 
give the command: 

(remove-entry-point (convert-to-lang "curpgmname"))) 

and then load your code. You can find out whether an entry point is present in 
LISP without going through the load step by using the function 

ff:get-entry-points name-list address-list Aoptional print [Function] 

■ This function takes a vector of names, each a string, and finds the 
memory address of each name inside the running LISP process. The 
address of the ith name is put in the it h position of address-list, which 
must be of type (simple-array (unsigned-byte 32) (*)). If a name is not 
found, the address is filled with value sys::*impossible-load-address* . 
The function returns the number of unmatched names in the name-list. 
The print argument is a Boolean variable (default nil), which, if t, will 
print useful information to the standard output. 

If you need to wipe out all the entry-point names for all previously loaded 
foreign code and start afresh, you should use the function 

ff:reset-entry-point-table [Function] 

■ This function has no arguments and restores the list of all entry-point 
names to be the same as when the LISP process started. All foreign code 
is still present and any LISP functions already defined for that foreign code 
will still work. 
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Once the foreign code is loaded, the calling convention to invoke the foreign 
function must be specified to LISP. This includes specifying: 

1 The name of the function in LISP; 

2 The name (or entry point) of the function in the compiled foreign code (if 
not specified, a default name depending on the LISP name and the foreign 
language is used); 

3 The arguments that the foreign function expects, the passing convention 
for each argument, and whether argument checking should be turned on or 
off; 

4 The type of the return value of the foreign function; 

Foreign functions that are called by other foreign functions but not by LISP 
need not be specified to LISP. 

Defining a foreign function to LISP is the job of the LISP function 
ffrdefforeign. Before showing it in its full generality, we give an example. 
Say we have the following C function: 


int 

add2 (x. 

y) 

i 

int x, 

y: 

i 

return 

x+y; 


compiled in the file Then the following LISP session loads and runs this func- 
tion, returning the sum. 


<cl> (load "add2.r") 

;; load the foreign code into LISP 
T 

<cl> (def foreign ' add2 : arguments ' (fixnum fixnum) 

: return-type : integer) 

;; return a LISP integer 
T 

<cl> (add2 3 5) 

;; invoke the foreign function 

8 


(The LISP type fixnum is used instead of integer in specifying the arguments 
since a LISP integer can be a bignum, which can be larger than the biggest pos- 
sible C integer.) In this example there are many default values in the function 
ffrdefforeign. For example, no argument checking was specified and it 
defaulted to t. Function ffrdefforeign is next presented in full generality. 
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ff:defforeign lisp-name &key ’.entry-point ’.arguments :pass - [Function] 

type :arg-checking -.return-type language ’.print 
icon vert-symbol ’.address ’.remember-address 

■ This function defines the calling convention which allows LISP to call 
a foreign function correctly, passing arguments of the correct type, and 
interpreting the returned value correctly, lisp-name is the name by which 
LISP will refer to the foreign function. 

□ The following are the keyword arguments to ff:defforeign. 

•.entry-point foreign-name [Keyword] 

■ This keyword’s value foreign-name is the name of the entry point 
as found in the compiled foreign code. In general, this will be lisp- 
name converted to follow the conventions of the language and the 
system, so this defaults to 

(convert-symbol lisp-name) 

where convert-symbol is the conversion function given in the key- 
word argument ’.convert-symbol described below. 

; arguments ( argument-type+ ) [Keyword] 

■ This specifies the arguments that will be passed to the forreign 
function. Its value must be a list of valid LISP types (e.g. the expres- 
sions integer, string, (simple-array double-float), etc.), or t, which 
converts arguments according to their type, whatever they are, or nil, 
which means no arguments. Valid types are given in Tables 8.1 and 
8.2 at the end of this chapter. Defaults to t. 

:pass-type ( passing-convention+ ) [Keyword] 

■ This keyword specifies the passing convention of each argument. 
The choices are pass by address (FORTRAN style) and pass by value 
(C style). The default is the style of the language specified, so users 
will rarely have to use this keyword. If the C code passes arguments 
by address, however, then this keyword should be used and its value 
should be a list of the same length as the argument list with elements 
:by-value if the corresponding argument is passed by value and :by- 
address if it is passed by address. 

:arg-checking boolean [Keyword] 

■ This argument defaults to t, in which case LISP will check that the 
arguments passed through to the foreign function are of the types 
specified in ’.arguments. Ignored if arguments is t. 
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:return-type return-type [Keyword] 

■ The value of return-type must be one of the keywords integer, 

:fixnum, ‘.single-float, ‘.double-float, character, -.void, which 
indicates no value is returned, or '.lisp, which indicates a lisp value is 
returned (normally used only if a C program returns a value accessed 
by the C library routine lisp_value()). Defaults to ‘.integer. 

language language-name [Keyword] 

■ This keyword is included to facilitate possible extensions to 
languages other than C. The only allowable value is keyword :c. 
which is also the default. Ignored if ‘.entry-point is specified. 

:print boolean [Keyword] 

■ If t, information useful for debugging will be printed to 

*terminal-io* . Defaults to nil. 

: convert-symbol conversion-function [Keyword] 

■ This keyword’s value conversion-function is the name of the func- 
tion that does the conversion of the lisp name to an entry-point name. 

The function must take as arguments a symbol and the keyword 
language, and must return a string recognizable to the operating 
system as an entry-point name. Default is ff :convert-to-lang defined 
above. 

-.address entry-point-address [Keyword] 

■ The entry-point-address may be supplied as the in-memory 
address of the entry point instead of the entry-point name. Normally 
not used and ignored if :entry-point is specified. This argument 
must be of type (simple-array (unsigned-byte 32) (1 )) (a one-element 
simple array of 32-bit integers) containing the in-memory address of 
the entry-point. 

: remember-address boolean [Keyword] 

■ If set to t, the in-core memory address of the foreign function is 
saved on the property list of lisp-name as the value of property 
ff::foreign-addr. Default is nil. 

Function ffidefforeign returns a function lisp-name, which passes its argu- 
ments through to the foreign code and returns the return-value of the foreign 
function to LISP. The passing convention depends on the type of argument and 
the language. For example, C normally expects its arguments to be passed by 
value, FORTRAN expects arguments to be passed by address. Tables 8.1 and 
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8.2 describe exactly how arguments are passed. 

Identifying a foreign function involves a very slow library function. To 
avoid this wait when defining many foreign functions, the LISP function 
defforeign-list is provided. This takes as one argument a list of lists of the 
arguments normally passed to ffrdefforeign and returns the number of unsuc- 
cessfully defined foreign functions. 

ff:defforeign-list ( arg-list+ ) [Macro] 

■ This function is equivalent to (but faster than) the LISP form: 

(do ((list list-of-arg-lists (cdr list))) 

((null list)) 

(apply #’defforeign (car list))) 


We give some examples. Consider a C function that adds three numbers and 
returns a double. 


♦include <stdio.h> 
double t_double(x, y, z) 
double x; 
float y; 
int z; 

{ 

double w; 
w=x+y+z; 
return w; 

} 


Say this is in a compiled C file test.r. Here is that test.r being loaded into LISP. 


<cl> (use-package 'ff) 

;; use foreign function package 
T 


<cl> 

; Foreign loading /a/cl-f f /test . r . 

T 

<cl> (defforeign 
't -double 

: entry-point (convert-to-lang 
"t_double" 

: language : c) 

: return-type : double-float 
: arguments ' (double-float single-float 
f ixnum) ) 

T 

<cl> (t-double 2 . 5d0 4.5 3) 

lO.OdO 
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If you want to live dangerously and speed up the calling procedure, set :arg- 
checking to nil in the ff:defforeign form. Then, no argument checking is 
done and the call to t_double() is faster. But, if there are errors passing argu- 
ments, the LISP process may fail mysteriously and unreproducibly. For exam- 
ple, with :arg-checking set to nil, the call 

(t-double 0 4.5 3) 

is likely to result in a bus error or a memory fault, causing a LISP error. 

To illustrate the use of the :convert-symbol keyword, you could define 
the above function t-double by using: 

(defun dash-to-underscore 
(symbol &key (language :c)) 

(let ((str (convert-to-lang 

symbol language language))) 

(dotimes (n (length str)) 

(if (eql (aref str n) #\-) 

(setf (aref str n) #\_))) 

str)) 

followed by: 

(defforeign 't-double 
:return-type :double-float 
arguments ’(double-float single-float 
fixnum) 

:convert-symbol ’dash-to-underscore) 

This takes the symbol t-double and converts it to the entry-point name 
corresponding to the function call in C given as t_double(). 


Arguments to function calls can be passed in two ways, by value and by 
address. When an argument is passed by value, a copy of the value is placed 
somewhere (typically on the stack) where the function can access it. When an 
argument is passed by address, a pointer to its actual location is given to the 
function. Arguments in C are usually (but not always) passed by value. 

When an argument is passed by address in C and the called function 
changes the value of the argument, the argument will stay changed even after 
control returns from the called function. The actual stored value of the argu- 
ment will have been permanently modified. This is expected behavior and is 
generally what is intended and desired. Users therefore should be warned that 
in many cases, when LISP code calls a foreign function that modifies one of the 
arguments passed by address, the LISP value of that argument will be 
unchanged. The reason is that LISP represents objects differently from C and, 
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therefore, cannot pass the actual address of the LISP object to the foreign code, 
since the foreign code would not correctly interpret the value pointed to. 
Instead, LISP makes a copy of the LISP object, changing the representation 
appropriately, and passes the address of the copy. Although this copied value 
is modified by the foreign code, LISP ignores the copied value after the func- 
tion returns, looking only at the unmodified LISP object. 

To repeat the above warning: functions which receive their values by 
address do not always affect the value of a LISP object when this is passed to 
the function. The following example illustrates this behavior. Say we have the 
C file cnames.c containing the function itimes2(). 

itimes2 (x) 
int *x; 

{ 

*x = 2* (*x) ; 
return (*x) ; 

} 

which appears to double the C integer value stored in the location x. If we 
compile and load this file into LISP, then run this function, as in the following 
session: 

<cl> (load "cnames.r") 

T 

<cl> (def foreign ' itimes2 : arguments ' (fixnum) 

:pass-type :by-address) 

;; send in a fixnum, but pass by address 
T 

<cl> (setq x 19) 

19 

<cl> (itimes2 x) 

;; gives 38 as expected 
38 

<cl> x 

;; but x is unchanged 
19 

The problem is that a LISP fixnum is not the same as a C integer, and thus the 
foreign-function interface must convert it. It copies the LISP fixnum, converts 
it to a C integer, and then passes the address of the converted copy to the func- 
tion. The expected behavior can be achieved by passing an array instead of a 
fixnum. 
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<cl> (defforeign 
' itimes2 

: arguments '( (simple -array fixnum (1))) 

: pass -type : by -value) 

T 

<cl> (setq x (make-array 1 

: element -type 'fixnum 
: initial-element 19)) 

# ( 19 ) 

<cl> (itimes2 x) 

;; gives 39 as expected 
38 

<cl> x 

; ; as does x 

# ( 38 ) 


So some LISP objects cannot be changed by passing them to foreign functions, 
and some can. 

Another difficulty arising out of differing LISP and non-LlSP representa- 
tions of values is illustrated by the example just given. The argument passed to 
the foreign function was a fixnum, not an integer. Integers can be bignums or 
fixnums. C integers may be larger than all possible LISP fixnums and smaller 
than most but not all bignums. If a fixnum is passed to foreign code, it is 
always correctly represented, but a bignum can be represented only if it is small 
enough. The foreign-function interface will truncate any bignum that does not 
fit into the foreign integer representation without warning. Users can avoid this 
by not using targument integer (and thus not passing bignums ) except when 
the argument value was generated by foreign code. The return value from 
foreign code defaults to type integer, and since some foreign integers are too 
big to be fixnums, they may be bignums. But, since they came from foreign 
code, they will be correctly represented as foreign integers when passed back to 
foreign code. In that case only is :argument integer recommended. 

An example illustrates the use of arrays. Say there is a compiled C file 
myreverse.r: 


int myreverse (n, x) 

double *x; /* pointer to array of doubles */ 
int n; /* array length */ 

{ 

int i; 
double d; 

for (i=0; i <= n/2; i++) { 

d = x [ i ] ; 
x C i ] = x [n-l-i] ; 
x[n-l-i] = d; 

} 

return n; 
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} 


in LISP you might define (after loading myreverse.r ) this function as follows: 


<cl> (def foreign 
' myreverse 
: arguments ' (fixnum 

(array double-float) ) 

T 

<cl> (setq x (make-array 
3 

: element-type 'double-float 
: initial-contents ' (1 . OdO 

2 . OdO 
3. OdO))) 

# (1 . OdO 2. OdO 3. OdO) 

<cl> (myreverse (length x) x) 

3 

<cl> x 

# (3 . OdO 2. OdO l.OdO) 


8.5 

Passing 
arrays of 
strings from 
Lisp to C 


A common usage in C is typified by the following program fragment: 


fdefine NULL 0 

char *z[] = {"stringsl", ,, string2", NULL}; 
handle_st rings (z) ; 


handle_strings (argv) 
char **argv; 

{ 

while ( *argv != NULL ){ 

handler_for_string (*argv) ; 
argv = argv + 1; 

} 

} 


Similar usage is also common with the array size included: 


char *z[] = {"stringsl", "string2", "string3"}; 
handle_st rings (3, z) ; 


handle_strings (argc, argv) 
char **argv; 
int argc; 

{ 
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} 


The variable argv is an array with each element pointing to a C string in both 
cases. (Note, however, that in the first case a NULL pointer terminates the 
array.) One would like to call handle_strings() from Lisp (after doing a 
ffrdefforeign) by something like the following: 

(handle_strings (make-array 3 :initial-contents 

’("stringl" "string2” 0))) 


or: 


(handle_strings 3 (make-array 3 :initial-contents 

’(“stringl" ”string2" “string3"))) 

depending on the definition of handle_strings() above. However, the 
foreign-function interface does not normally convert the individual elements of 
a LISP array. 

The conversion will be done if the foreign function has the appropriate 
argument declared to be of type (simple-array simple-string (*)). While this is 
not implemented as a distinct data type in Tek COMMON LISP, the foreign- 
function interface will recognize this declaration and convert the array 
appropriately for C. This is a slow function call as the interface must allocate 
space to do the conversion. So to get the desired behavior (e.g. for the second 
of the above two possibilities for handle_strings()) you should use: 

(defforeign ’handle_strings arguments 
’(fixnum (simple-array simple-string (*)))) 

Note that if you do not declare arguments — e.g. if you use: 

(defforeign ’handle_strings arguments t) 

the array will not be converted correctly on the call to handle_strings(). Note 
that this is not typical; the interface normally converts arguments according to 
their LISP data type whether or not they are declared. 

If you do make this declaration and pass in an arbitrary LISP array, all bets 
are off. Only 0 and array elements of type simple-string are guaranteed to be 
correctly converted. 
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8.6 

Defining and 
calling Lisp 
functions 
from foreign 
code 


This section describes the Tek COMMON LISP facility that permits C functions 
to call LISP. The C functions must have been loaded into LISP and have been 
called from LISP. 

Because some LISP objects move in memory when a garbage collection 
occurs, calling out to LISP must be used with great care on the part of the C 
programmer. As an example, if an array is passed to a C function which calls 
out to a LISP function and a garbage collection occurs, then after the C function 
returns, the pointer to the array will point to nothing; the array data will have 
moved somewhere else. So if a C function accesses a LISP value and calls out 
to LISP, then it is recommended that the LISP value be registered and accessed 
as described next. 

To give a particular example, let us say: 


1 You register a LISP object (e.g. an array). (This is detailed below.) 

2 You use ffrdefforeign to define a C function with return type :lisp. 

3 In the C program you retrieve and use the registered LISP value. 

4 You call out to a LISP function and a garbage collection occurs — the LISP 
value in C is no longer valid. 

5 The C function returns the LISP value it retrieved earlier. 

6 Then on the next garbage collection LISP dies because of an illegal object 
reference: the LISP value returned by the C function no longer points to 
valid data. 


The problem only occurs if a garbage collection happens during the call to the 
LISP function. What you should do is to make sure that any LISP value you 
return to LISP or work with within a C function is retrieved only after there is 
no possibility of calling out to a LISP function where a garbage collection may 
occur. To fix the example above so it is safe, you should add another step after 
step 4: 

4a Retrieve the registered LISP value again. 

Other scenarios can be played out, for example where C changes array data 
using an invalid array pointer — LISP never sees the changes. 

For purposes of allowing call-backs from foreign code, Tek COMMON 
LISP maintains two tables of LISP objects: one is the function table and the 
other is the value table. The LISP program can ‘register’ functions or values by 
requesting that they be stored in the respective table. The size of the value 
table will grow dynamically, but the size of the function table is fixed to the 
value of comp::foreign-callback-table-size. This cannot be changed, and is set 
to 1000 in this release. 

In LISP, there are the following functions (in the foreign-function package, 
nicknamed ff). 


0 - 01 - 02 ( 2-1 
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ff :register-value value &optional index [Function] 

■ The value is stored in the table of foreign values at the requested index, 
if index is given; or in a free slot if index is not given. Two, values are 
returned: the index and the previous value at that index (or nil if there was 
no previous index). 

ff:register-f unction symbol-or-compiled-function-object [Function] 

&optional index 

■ The symbol-or-compiled-function-object is stored in the table of foreign 
functions at the requested index, if the index is given, or in a free slot if 
the index is not given. Three values are returned: 

1 An integer which can be passed to C and used to directly call to this 

function using the (*f)(arg1 , arg2 argn) syntax given below. 

2 The index in the table used where this function is stored. This index 
can be used in the lisp_call() function. 

3 The previous value at this slot (or nil if there was no previous value). 

Once a value is registered, the C program can obtain the value from the value 
table with the C function: 

long lisp_value(index) 
int index; 

where index is the index of the registered value in the value table in LISP. This 
C function will always return the current value at the index index even after a 
garbage collection has occurred. The result value from lisp_value() will be a 
LISP object and macros are provided to help C analyze the LISP object and con- 
vert it to something meaningful. These macros are found in the C header file 
lisp.h, usually distributed in the lib/misc directory with Tek COMMON LISP. 

The C program can request that the function in the function table be 
evaluted inside LISP by using the C function lisp_call(). The form is 

long Iisp_call(index,arg1 ,arg2,...,argn) 
int index; 

where index is the index of the registered function in the function table. The C 
arguments need to be turned into LISP arguments so that the LISP function can 
use them. There is no type information in C, so you must declare these argu- 
ments when you define the LISP function. This is done with the macro defun- 
c-callable, which acts like defun, but defines the function as one called by C 
(details and an example given a little later). Iisp_call() returns the return value 
of the called LISP function. The returned value is not converted to be a C style 
value, and nor is the returned value of lisp_value(). 

The following LISP function may be useful for debugging code. It simu- 
lates the C function lisp_value() , but may be called from within LISP at any 
time. 
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ff:lisp-value index [Function] 

■ This returns the value in the table at the given index. 

Function code is never garbage-collected and thus does not move in Tek COM- 
MON LISP, so a C program can also call a LISP function using the syntax 
(*f)(arg1, arg2, ..., argn), where the value of f is an integer determined by the 
LISP function register-function. 

For example, say we have loaded the compiled C file: 


void c_calls_lisp (fun, index) 
long ( *fun) ( ) ; 

{ 

(*fun) () ; 

/* direct call to LISP function */ 
lisp_call (index) ; 

/* call to LISP function using index */ 

} 


and had the following session in LISP: 


<cl> (setq called 0) 

0 

<cl> (defun-c- callable lisp-talks () 

(format t "This is Lisp called for the ~:r 
time. "%" 

(setq called (1+ called) ) ) ) ) 

LISP-TALKS 

<cl> (multiple -value -bind (ptr index prev-ptr) 
(register-function 'lisp-talks) 

(list ptr index prev-ptr) ) 

(1404302 0 NIL) 

;; ptr is 1404302, index 0 in 
;; function table, previous 
;; function none 
<cl> (def foreign 

' c-calls-lisp 

: entry-point (convert -to-lang 
" c_call s__li sp " ) 

: arguments ' (integer fixnum) 

: return-type : void) 

T 

<cl> (c-calls-lisp ptr index) 

This is Lisp called for the first time. 

This is Lisp called for the second time. 
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The C representation and the LISP representation of data types are not 
necessarily the same. When a C function calls a LISP function, The LISP func- 
tion needs to have its arguments declared so that it ‘knows’ what the C argu- 
ments were and how to convert them. This declaration scheme is wrapped in a 
macro defun-c-callable. 

ff :defun-c-callable lisp-function-name ( { arg | (arg type) }* ) body- [Macro] 
form+ 

■ Each arg is an argument which C passes to LISP. This macro does not 
allow &rest or &optional arguments in the argument list. Each argument 
is either a symbol (as in the usual function definition), or it is a list of 
length two, a symbol and its type. If a symbol only is present, then it has a 
default type. The type corresponds to the type of a C argument and is 
currently limited to be one of the following: 


:signed-byte 

8 bits 

:unsigned-byte 

8 bits 

:signed-word 

16 bits 

:unsigned-word 

16 bits 

:fixnum 

29 bits 

:signed-long 

32 bits (the default) 

:unsigned-long 

32 bits 

:lisp 

(Assumes that C passes an 
actual LISP value.) 


□ If the type is not present, it defaults to signed-long. 

We give an example: say that we define the following C function, compile it 
and load it into LISP: 


void add(x, y, index) 
int x, y, index; 

{ 

lisp_call (index, x, y) ; 

} 


8.7 
How 
foreign- 
called Lisp 
functions get 
arguments 


Then the following LISP session could take place: 
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<cl> (deff oreign ' add 

: arguments ' (integer integer fixnum) 

: re turn -type : void) 

T 

<cl> (defun-c-callable add-two-c-args 

( (x : signed-long) (y : signed-long) ) 
(setq xy (+ x y) ) ) 

; ; set a global variable 
; ; to the sum of x and y 
ADD-TWO-C-ARGS 
<cl> (setq index 

(cdar (multiple-value-list 
(register-function 
' add-two-c-args) ) ) ) 

1 

<cl> (add 4 5 index) 

;; call to the foreign function 

NIL 

<cl> xy 

;; test the value of the 
;; global variable xy 
9 


Note that in the example above, we get exactly the same result by omitting the 
type declarations for the function add-two-c-args (i.e. we could have defined 
it as: 

(defun-c-callable add-two-c-args (x y) 

(setq xy (+ x y))) 

since the default is to assume the arguments are signed-longs. 

Some more detail on exactly how a LISP function gets C arguments fol- 
lows. The defun-c-callable macro expands into something defined in terms of 
the following. 

Really, exactly one argument is passed from C to LISP — a descriptor that 
tells LISP how to access the C arguments and turn them into LISP objects. 
(This ‘descriptor’ is actually a pointer at the memory position where the C 
function stacked its arguments). The LISP function foreign-argument uses 
this ‘descriptor’ to access the C arguments. 

ff ’.foreign-argument descriptor arg-number &key :type :skip - [Function] 

bytes 

■ This returns the argument numbered arg-number (first argument counts 
as arg-number 0 ) from the list of arguments passed from C to LISP. The 
‘.type tells LISP how to convert the C argument to a LISP type and can be 
one of: 
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:signed-byte 

8 bits 

:ynsigned-byte 

8 bits 

:signed-word 

16 bits 

:unsigned-word 

16 bits 

:fixnum 

29 bits 

:signed-long 

32 bits (typical) 

:unsigned-long 

32 bits 

:lisp 

(Assumes that C passes an 
actual LISP value.) 


□ The arg-number can only be used to find the correct argument if all 
arguments are the same size (four bytes). If this isn’t the case, if for 
example a structure or double float is passed, then the calculation will be 
wrong. Thus the :skip-bytes value is used to skip a number of bytes of 
arguments (default zero). 

For example, suppose a LISP function called-from-c is defined and registered 
in the following LISP session: 


<cl> (defun called-from-c (desc) 

(format t "Second C arg is ~s" 
(foreign-argument desc 0 

; type : signed-long 
: skip-bytes 8) ) ) 

;; This skips 8 bytes (the size of a double) 
;; and then gets the zeroth argument . 
CALLED-FROM-C 

<cl> (register-function 'called-from-c 23) 

1404302 

;; the in-memory address C calls to 
; ; invoke CALLED-FROM-C 
23 

;; the slot number of the function table 

NIL 

;; the previous function in this slot 
;; (nil means none ) 


When a C function makes the call 
lisp_call(23, f, j) 
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8.8 

C structures 


where f is a double and j is an integer, the LISP function called-from-c will be 
called and output the value of j. 

Functions coded in C often use struct (structure) data types and pointers to such 
data as arguments and returned values. Tek COMMON LISP has an interface 
called cstructs to facilitate operations on foreign-language data types. 
Although the cstruct interface closely parallels C data typing, the facility is 
straightforwardly useful with other foreign languages. 

Consider the following example of the use of the struct data type in C. 
Most UNIX and UNIX-like operating systems feature a stat() system call that 
returns complete information about a file based on the per-file information kept 
on disk. The following model of the stat() system call does not correspond 
exactly to any particular system, but something similar to these C data defini- 
tions will be found in the operating system documentation. 

struct device { 

char major; 
char minor; 

}; 


struct stat { 

struct device st_dev; 
short inode; 
short st_mode; 
short st_nlink; 
short st_uid; 
short st _gid; 
struct device st_rdev; 
long st_size; 
long st_atime; 
long stjntime; 
long st_ctime; 

}; 


struct stat *stat(path, but); 
char *path; 
struct stat *buf; 

The stat() function is called with two arguments, the pathname of the file to be 
examined and the address of a stat C structure into which the file data will be 
placed. 

Three problems must be solved for a LISP program to use stat(): the func- 
tion itself must be made available via the foreign-function interface; LISP must 
have some way to allocate an appropriate object to serve as the second argu- 
ment to stat(); and LISP must have accessor mechanisms for the slots of the 
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structure. The first is accomplished with the ff:defforeign function. The 
remaining two are satisfied using the ff:defcstruct macro. The C structure stat 
from the C example above could be defined for LISP using ff:defcstruct as fol- 
lows: 

(ff:defcstruct device 
(major :char) 

(minor :char)) 

(ff.-defcstruct stat 
(dev device) 

(inode :short) 

(mode :short) 

(nlink :short) 

(uid :short) 

(gid ishort) 

(rdev device) 

(size dong) 

(atime :long) 

(mtime dong) 

(ctime dong)) 

(ff:defforeign ’stat) 

ff:defcstruct name slot [slot ...] [Macro] 

■ This macro defines a C structure to LISP by defining appropriate acces- 
sor and creator functions. The creator function is named make-name. 

The accessor function names for each slot are the hyphen-separated con- 
catenation of the cstruct name and the slot name. The creator and acces- 
sor functions are described in greater detail below. 

□ Argument name is either the name of this cstruct or a list. In the latter 
case the first element of the list is the name of the cstruct and the remain- 
ing elements are options described below. 

□ Each slot is a list. The first item on the list is a symbol naming the slot, 
and the rest of the list is a data type. A data type takes one of the follow- 
ing forms: 

□ A single keyword, which is one of the following: :char, tbyte, 

.-short, tlong, :unsigned-byte, tunsigned-short, tunsigned-long, 
tshort-float, or tlong-float. This will provide space for the specified 
atomic C data type to be placed in that slot. 

□ A symbol, which must name of a previously defined cstruct. 

□ * data-type where data-type is any valid data type. As in C, the * 
indicates that the slot will contain a pointer to an object of the speci- 
fied type. Also, as in C, if data-type is a symbol, the requirement is 
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relaxed that a structure of that name must already be defined. 

□ integer [integer...] data-type Again, data-type is any valid (possibly 
compound) data type, which may include the pointer *. The integers 
denote an array of the indicated dimensions. The accessor 
function(s) will accept appropriate subscript argument(s). 

□ slot [slot ...] cstructs may include other cstructs. Here slot is recur- 
sively defined as another list. This is similar to including another 
cstructs by name. 


8.8.1 

Accessing 

slots 


The slots of a cstruct are accessed by functions defined by the expansion of the 
ff:defcstruct macro. Accessor functions are named by concatenating the 
cstruct name with the slot names, separated by hyphens. The accessor function 
name for a compound slot — that is, a slot which contains another named cstruct 
or whose data type is a list of named slots — is the hyphen-separated concatena- 
tion of all its cstruct and slot names. For example, the i-node number is 
accessed by the function stat-inode, and the device upon which that i-node 
resides is accessed by the function stat-dev-major. 

All accessor functions take a cstruct as argument, and return the value in 
that slot. Slot accessor functions are understood by setf. The compiler 
expands cstruct accessors and setf forms inline. 


8 . 8.2 
Storage 
allocation for 
cstructs 


If the name of the cstruct being defined is name, the creator function is named 
make-name. This function creates an object in which the slot data can be 
stored. In the above example the creator function will be make-stat, which 
will create a Lisp object of type (simple-array (unsigned-byte 32) (8)). The 
ff:defcstruct facility provides two distinct types of C structures distinguished 
by how and where their storage is allocated. A cstruct can be allocated in regu- 
lar LISP heap space (the part of memory that is garbage-collected by the LISP 
system) or else it can be allocated in C space. The difference between the two 
allocation methods is that C space is not garbage-collected, and therefore the 
data is never moved by the garbage collector. LISP heap space is regularly 
freed up by the garbage collector. Objects that are still active are moved when 
a garbage collection occurs. Structures allocated in C space, whether by LISP, 
by being declared at compile time in a foreign subroutine, or by the C function 
malloc(), are not affected by the garbage collector. Although the usage is the 
same, the internals of the accessor functions for structures located in LISP heap 
space are necessarily different from those located in C space. Therefore, the 
difference must be specified when the cstruct is defined, with the ff:defcstruct 
macro. 

There are two reasons why it may be necessary to define a cstruct to be in 
C space. In some cases LISP needs to access storage allocated by C routines, 
which obviously will be in C space. In others cases the C code may retain a 
pointer to a cstruct passed to it when LISP resumes control. The garbage 
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collector may be invoked any time that LISP is run, and pointers from foreign 
space to a cstruct will not be forwarded by the garbage collector. Therefore 
such a cstruct cannot be in LISP space. 

By default ff:defcstruct defines a structure which will occupy LISP space. 
To define a structure which will occupy C space the keyword tmalloc must be 
given as a ffidefcstruct option in the first subform. Such cstructs are called 
malloc - style cstructs. LISP represents a pointer to an instance of a malloc - style 
cstruct as an integer, which is its memory address. This is reminiscent of C 
pointers. 

In the above example, a stat structure was allocated in Lisp space and 
passed to the stat() C function to be filled in. What follows is an example 
using a malloc - style cstruct. Most UNIX systems provide a standard 
input/output facility called the Standard I/O Library, or stdio. Functions that 
open a stream return a pointer to a FILE structure that represents the stream. 
The stdio facility maintains storage for FILE objects in C space, so a LISP pro- 
gram that (for whatever reason) wanted to use stdio would have to use a 
malloc - style cstruct. The following code describes one implementation of a 
FILE structure in C. 

extern structjobuf { 

unsigned char *_ptr; 
int _cnt; 

unsigned char *_base; 
short _fiags; 
char _fileno; 

}; 

Then the following LISP code will define an ‘equivalent’ cstruct to LISP: 

(ff:defcstruct (iobuf :malloc) 

(ptr * :char) 

(cnt tint) 

(base * :char) 

(flags :short) 

(fileno :char)) 

Note the use of pointer data types, indicated by *. Note too that the C name 
conventions have been made LlSP-like by eliminating underscores. 


The expansion of fftdefcstruct defines a creator function make-name. Two 
other creator functions exist that take a cstruct name as an argument, but other- 
wise have the same effect as make-name. 


8.8.3 
Allocating 
and freeing 
cstructs 
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make-cstruct name [Function] 

■ This function returns a new instance of the cstruct named name, which 
must have already have been defined with the ff:defcstruct macro. Both 
ordinary and malloc- style cstructs may be created with this function. 

malloc-cstruct name [Function] 

■ This function creates a malloc- style cstruct. The cstruct named by 
name, which must already have been defined with the ff:defcstruct 
macro as a malloc- style cstruct. This function is slightly faster than 

make-cstruct. 

Since malloc- style cstructs are not garbage-collected, the user has the responsi- 
bility of freeing their storage when they are no longer needed. The following 
function deallocates space for malloc-style cstructs. 

free-cstruct cstruct-instance [Function] 

■ This function frees space allocated to the malloc- style cstruct cstruct- 
instance. 

The initial content of a cstructs slot defined by ff:defcstruct is undefined and 
the creator functions just described make no provision for initialization. Initial 
slot contents are unpredictable. Even trying to print a slot’s contents, for 
example, may result in an error. LISP code can initialize a slot only by a setf 
of the slot accessor function. 


8.8.4 
Pointers, 
embedded 
structures, 
and arrays 


As shown abive, C structure slots are often compound. A pointer to any data 
type may be specified with a *, as in the iobuf example above. A cstruct slot 
may contain an embedded substructure instead of an atomic data type. Such an 
embedded structure is specified by providing as its data type either the (non- 
keyword) name of a previously-defined cstruct or a list of named slots. 
Further, the cstructs package permits arbitrary levels of array specification by 
prefixing any simple or compound data type with integer dimension values. 
Here are some examples showing arrays and embedded substructures. In C, we 
have: 

struct fft_buf_1d { 

struct { float real, imag; } point[1024]; 

}; 


struct fft_buf_2d { 

struct { float real, imag; } point[64][64]; 

}; 
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The equivalent cstruct definitions in LISP are 
(ff:defcstruct fft-buf-1 d 

(point 1024 (real :short-float) (imag :short-float))) 

(ffidefcstruct fft-buf-2d 

(point 64 64 (real :short-float) (imag :short-float))) 

In addition to the usual first argument which is the object itself, accessor func- 
tions for dimensioned data take one additional subscript argument for each 
dimension. Subscript arguments must evaluate to integers, but do not undergo 
range checking. 

As a guide for translating C declarations into LISP, it should also be clear 
by now that structure slot definitions in C and LISP employ approximately 
reversed component orderings. In C the slot name follows the data type, in 
LISP it precedes. The pointer indicator * follows the data type in C and pre- 
cedes it in LISP. However, array dimensions follow their slot names in both 
languages, and the subscript ordering in both C and LISP places the most- 
rapidly varying subscripts last. Consider the following example: 

struct too { char a[3][5]; } my_foo; 

The structure contains three strings of length five. One accesses the fourth 
character of the second string with 

my_foo.a[1 ][3] 

In LISP, the cstruct is defined and created by 

(ffidefcstruct foo (a 3 5 :char)) 

(setq my-foo (make-foo)) 

and the fourth character of the second string is accessed by 
(foo-a my-foo 1 3) 

Although it makes sense in C to operate on an embedded substructure or 
part of an array (i.e., to take its address, pass it as an argument, or test it for 
equality with another) it does not make sense in LISP to define accessors for 
non-atomic components because there are no corresponding I data types. Com- 
pound slots may be dimensioned, however, and the subscript arguments will be 
inherited by the accessor functions of all contained slots. For example: 

(ffidefcstruct two-fft-bufs-2d (buf 2 fft-buf-2d)) 

(setq fft-bufs (make-two-fft-bufs-2d)) 

(two-fft-bufs-2d-point-real fft-bufs 1 8 7) 

The last expression accesses the real component of element [8][7] in the second 
of two two-dimension fft buffers. 
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8.8.5 

Portability 

issues 


C compilers differ radically in the alignment and size of data types. Obviously, 
any use of the cstruct facility makes a COMMON LISP program non-portable. 
However it might sometimes be appropriate to use similar foreign function rou- 
tines on different target machines. A programmer writing a sophisticated inter- 
face between LISP and C code using ff:defcstruct is encouraged to check 
agreement between the languages by comparing the expansion of the 
ff:defcstruct macro with code produced by the particular C compiler. The 
cstruct facility attempts to generate accessors that are correct for the local 
machine, but these accessors will not necessarily be correct on a different type 
of machine, and sometimes the data alignment behavior of a particular C com- 
piler will change between releases. 

Existing C compilers differ in these ways: slots of type :long, pointers, 
and floating data, are aligned on either 2 or 4 byte boundaries; and the overall 
size of a outermost C structure is padded to 4 bytes instead of 2 in some imple- 
mentations. 


8.9 

Argument- 

passing 

synopsis 


The following two tables summarize information on argument-passing between 
LISP and C. Table 8.1 shows how the principal LISP data types are passed by 
value to C. Table 8.2 shows how these data types are passed by reference to C. 


DSP type 

Procedure 

Declaration 

fixnum 

converted to machine integer 

int arg; 

single-float 

converted to machine single-float 

float arg; 

double-float 

converted to machine double-float 

double arg; 

character 

converted to C character after font and other 
attributes have been removed 

char arg; 

array 

pointer to array is passed; for displaced arrays, a 
pointer to the data at the displacement offset is 
passed; arrays of fixnums behave as expected, 
fixnums being stored in arrays as machine 
integers; for bit arrays that are displaced to other 
bit arrays, a pointer is passed to the data byte 
addressed by the displacement divided by eight 
(rounded down); LISP array elements can be 
changed by C 

int *arg; 
float *arg; 
(etc.) 

string 

a special case of arrays: they are always NUL- 
terminated 

char *arg; 
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(vector 

simple-string) 

if declared, a new vector is allocated and each 
slot filled with a pointer to the actual string; this 
new array is passed in the usual way; if not 
declared, no conversion is performed, and a 
pointer to an array of LISP objects is passed 

char **arg; 

bignum 

truncated to a machine integer 

int arg; 

other types 

unimplemented; strange things will happen 


Table 8.1. By-value passing conventions to C. 


Lisp type 

Procedure 

C Declaration 

fixnum 

copy is made of the fixnum, converted to machine 
integer, and pointer to converted copy is passed; 
LISP value is not changed 

int *arg; 

single-float 

pointer to that part of the LISP object containing a 
machine single float is passed; LISP value may be 
changed by C or FORTRAN 

float *arg; 

double-float 

pointer to that part of the LISP object containing a 
machine double float is passed; LISP value may 
be changed by C or FORTRAN 

double *arg; 

character 

copy is made, converted to a C character, and a 
pointer to the converted copy is passed; LISP 
value is not changed 

char *arg; 

array 

pointer to array is passed; for displaced arrays, a 
pointer to the data at the displacement offset is 
passed; arrays of fixnums behave as expected, 
fixnums being stored in arrays as machine 
integers; for bit arrays that are displaced to other 
bit arrays, a pointer is passed to the data byte 
addressed by the displacement divided by eight 
(rounded down); LISP array elements can be 
changed by C; (this procedure is identical to that 
for passing arrays ‘by value’) 

int *arg; 
float *arg; 

(etc.) 

string 

a special case of arrays: they are always NUL- 
terminated 

char *arg; 


(vector 

simple-string) 
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if declared, a new vector is allocated and each char **arg; 

slot filled with a pointer to the actual string; this 

new array is passed in the usual way; if not 

declared, no conversion is performed, and a 

pointer to an array of LISP objects is passed; (this 

procedure is identical to that for passing arrays 

‘by value’) 

bignum 

unimplemented; strange things will happen 

other types 

unimplemented; strange things will happen 

Table 8.2. By-reference passing conventions to C. 
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9 Packages 


Tek COMMON Lisp allows the use of packages to keep different parts of an 
application separate, permitting multiple use of symbol names and independent 
development of different parts of a large program. See chapter 1 1 of Common 
Lisp for further details. Tek COMMON LISP comprises several packages, and 
users should be aware of what packages are available, which should be used by 
the user, and which should, in general, be avoided. 


The following packages used by Tek COMMON LISP are of direct importance to 
the user: 


lisp 

standard COMMON LISP 

excl 

extensions to COMMON LISP 

system 

relating to operating-system 

user 

user environment 

flavors 

object-oriented environment 


9.1 

Packages in 
Tek 
COMMON 
LISP 


When you start up Tek COMMON LISP, you are in the user package. At 
the start, there are no symbols in the user package, but the lisp and the excl 
packages are inherited by default, so external symbols from those packages are 
available to the user package. The lisp package contains only those symbols 
specified in Common Lisp. Some of the capabilities of standard COMMON LISP 
functions have extended, but they can all be used in the way specified in Com- 
mon Lisp. At the moment, only load has been extended (to allow loading of 
foreign code.) It is possible that further functions, particularly compiler func- 
tions, will also be extended in the future. Users who want the most portable 
code should not use these extensions, which will be described in the Release 
Notes. Therefore, if you use the lisp package only, you will have portable code 
which can with greatest ease be ported to COMMON LISP systems other than 
Tek COMMON LISP. (But see the comments about portability in the introduc- 
tion.) The excl package contains the COMMON LISP environment and many of 
the simple extensions. A list of external symbols in the Tek COMMON LISP 
package is given at the end of the chapter. In excl, the user gets access to the 
top level, the profiler, and so on. The system package should not be used since 
the user may inadvertently modify system variables, which may have strange 
and disastrous consequences. The flavors package contains the flavors system 
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9.2 

Symbols in 
the excl 
package 


described in chapter 6 of this manual. 

Chapter 1 1 of Common Lisp describes packages and their use. The user should 
refer to that chapter for the description of how to create, use or exclude pack- 
ages. 


The following table lists the symbols exported from the excl package. 


Symbol 

Type 

arglist 

function 

bignump 

function 

compile-file-if-needed 

function 

dumplisp 

function 

errorset 

function 

exit 

function 

ignore-if-unused 

declare specifier 

instancep 

function 

file-older-p 

function 

fixnump 

function 

function-call-report 

function 

function-call-run 

function 

gc 

function 

if* 

macro 

pp 

macro 

putprop 

function 

ratio p 

function 

set-case-mode 

function 

shell 

function 

single-float-p 

function 

uncompile 

function 

*gcprint* 

variable 

*compiler-package * 

variable 

*excl-package* 

variable 

*franz-package* 

variable 

*keyword-package * 

variable 

*lisp-package* 

variable 

*sys tem -package * 

variable 

*user-package* 

variable 

Table 9.1. List of symbols exported from excl pack- 
age 
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Summary of symbols 


+ . . . 5-20 
++ . . . 5-20 
+++... 5-20 
- . . . 5-21 
* ...5-21 
** ...5-21 
*** . . . 5-21 
/ . . . 5-21 

II ... 5-21 

III ... 5-21 

:abstract-flavor ... 6-31 
:accessor-prefix . . . 6-30 
:address entry-point-address ... 8-7 
:after ... 6-41 

top-level:alias {name | (name [option ...])} arglist body . . . 5-21 

:aliases ... 5-9 

.* alias-flavor ... 6-31 

*all-flavor-names* ... 6-17 

:and . . . 6-39, 6-41, 6-42 

■.append . . . 6-39, 6-42 

:arg-checking boolean ... 8-6 

arguments ( argument-type+ ) ... 8-6 

top-level:*auto-zoom* . . . 5-19 

bbcomp v . . . S-4 

bb-d . . . S-5 

bb-d-or-not-s ... S-5 

bb-not-d ... S-5 

bb-not-s ... S-5 

bb-not-s-and-d ... S-5 

bb-not-s-and-not-d ... S-5 

bb-not-s-or-not-d ... S-5 

bb-not-s-xor-d . . . S-5 

bb-one . . . S-5 

bb-s ...S-5 

bb-s-and-d ... S-5 

bb-s-and-not-d ... S-5 
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bb-s-or-d . . . S-5 

bb-s-or-not-d ... S-5 

bb-s-xor-d ... S-5 

bb-zero ... S-5 

; before . . . 6-41 

exckbignump object ... 3-9 

bit-bit bbcom . . . S-6 

*black-halftone* . . . S-19 

■.bottom ... 5-7 

•.break . . . 6-35 

: break-after val ... 5-11 

: break-all val ...5-11 

: break-before val ... 5-11 

-.brief ... 5-6 

-.call ...3-7 

-.case . . . 6-40 

:cf file* . . . 5-9 

char-draw char point . . . S-6 

char-draw-raw-x char point bbcom font . . . S-6 

char-draw-x char point bbcom font . . . S-7 

char-width char font . . . S-7 

excixhdir pathname &key simple ... 4-3 

circle-draw center radius ... S-7 

circle-draw-x center radius width bbcom ... S-7 

clear-screen . . . S-7 

-.combined . . . 6-42 

top-level:*command-char* . . . 5-19 

system :command-line-argument n ... 4-3 

system :command-Iine-argument-count ... 4-3 

system :command-line-arguments ... 4-3 

excl:compile-file-if-needed filename &key -.output-file :force-compile . . . 3-10 
compile-flavor-methods flavor-names* . . . 6-23 
compiler:declared-fixnums-remain-fixnums-switch ... 2-5 
compiler:*do-call-counts* ... 7-2 
compiler:generate-call-count-code-switch ... 2-5 
compiler:generate-interrupt-check-switch ... 2-5 
compiler:trust-declarations-switch ... 2-6 
compiler:verify-argument-count-switch . . . 2-6 
compiler:verify-car-cdr-switch . . . 2-6 
compiler:verify-non-generic-switch ... 2-6 
compiler:verify-symbol-value-is-bound-switch ... 2-6 
: condition expr ... 5-11 
:continue ... 5-5 

-.convert-symbol conversion-function ... 8-7 
ff:convert-to-lang string &key language ... 8-4 


D-01-02C-12- 



Tek Common Lisp 
S ummary of symbols A-3 


rcurrent ... 5-7 

excl:*current-case-mode* ... 3-2 
exchcurrent-directory ... 4-3 
cursor-track trackp . . . S-7 
cursor-visible visiblep . . . S-7 
•.daemon . . . 6-38 
:daemon-with-and . . . 6-38 
:daemon-with-or ... 6-38 
:daemon-with-override . . . 6-38 
★dark-grey-halftone* ... S- 19 

compiler:declared-fixnums-remain-fixnums-switch ... 2-5 

; default . . . 6-41 

:default-handler . . . 6-29 

:default-init-plist . . . 6-26 

ff:defcstruct name slot [slot ...] ... 8-21 

defflavor flavor-name (vars*) (flavors*) options* . . . 6-17 

ff:defforeign-list ( arg-list+ ) ... 8-8 

def method (flavor-name [method-type] operation) lambda-list forms* ... 6-17 

ff:defun-c-callable lisp-function-name ( { arg [ (arg type) }* ) body-form* . . . 8-17 

defwhopper (flavor-name operation) lambda-list &body body . . . 6-22 

defwrapper (flavor-name operation) lambda-list &body body . . . 6-21 

: describe . . . 6-34 

describe-flavor flavor-name . . . 6-25 

display-state-p v . . . S-4 

display-visible visiblep . . . S-7 

:dn ... 5-7 

:dn [n] ...5-7 

compiler:*do-call-counts* ... 7-2 
load filename &key :foreign-files ... 7-2 
top-level:do-command name &rest arguments . . . 5-22 
:documentation . . . 6-33 

exchdumplisp &key : name :restart-function :read-init-file [else else-form+] ... 3-10 
:entry-point foreign-name ... 8-6 
:error ... 5-5 

exckerrorset form [announcep] ... 3-4 
top-level:*eval* . . . 5-20 
:eval-inside-yourself form . . . 6-35 
event-clear-alarm . . . S-8 
event-disable ... S-8 
event-enable ... S-8 
event-get-count ... S-8 
event-get-new-count . . . S-8 
event-get-next ... S-8 
event-get-time . . . S-9 
event-set-alarm time . . . S-9 
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event-set-mouse-interval interval . . . S-9 
event-set-signal ... S-9 
exclrbignump object ... 3-9 
exclrchdir pathname &key simple ... 4-3 

excl:compile-file-if-needed filename &key -.output-file :force-compile . . . 3-10 
excl:*current-case-mode* ... 3-2 
exclrcurrent-directory ... 4-3 

exclrdumplisp &key : name restart-function :read-init-file . . . 4-4 

exclrerrorset form [announcep] ... 3-4 

exclrexit &optional val ... 4-4 

excl:file-older-p file-1 file-2 ... 3-10 

exclrf ixnump object . . . 3-9 

exclrf unction-call-clear ... 7-2 

excl:f unction-call-count function ... 7-2 

exclrf unction-call-list ... 7-1 

exclrf unction-call-report &optional number-to-report ... 7-1 
exclrgc ... 2-2 
excl:*gcprint* ... 2-2 

exclrgenerate-library-pathnames library-root-directory ... . 3-11 

exclrget-and-zero-call-count function ... 7-2 

exc!:*ignore-package-name-case* ... 3-2 

exclrinstancep object . . . 6-21 

excl::*library-code-cl-pathname* ... 3-9 

excl::*library-code-fasl-pathname* ... 3-9 

exclrpp name . . . 3-10 

exclrratiop object . . . 3-9 

exclrset-case-mode new-mode ... 3-2 

exclrshell &optional command ... 4-3 

exclrsingle-floatp object ... 3-9 

excl:*trace-output* ... 5-11 

excl:*trace-print-length* ... 5-11 

excl:*trace-print-level* ... 5-11 

exclruncompile function-name ... 3-9 

excl:username-to-home-di rectory name . . . 4-4 

exclrexit &optional val ... 4-4 

rexit [val] ...5-10 

exit-graphics ... S-9 

top-level:*exit-on-eof* . . . 5-19 

lisprexport ...3-11 

ff:convert-to-lang string &key language ... 8-4 
ffrdefcstruct name slot [slot ...] . . . 8-21 
ffrdefforeign-list ( arg-list+ ) ... 8-8 

ff:defun-c-callable lisp-function-name ( { arg | (arg type) }* ) body-form+ ... 8-17 
ffrforeign-argument descriptor arg-number &key :type :skip-bytes ... 8-18 
ff rget-entry-points name-list address-list &optional print ... 8-4 
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ff:lisp-value index . . . 8-16 

ffrregister-function symbol-or-compiled-function-object Aoptional index ... 8-15 

ff:register-value value Aoptional index . . . 8-15 

ff:remove-entry-point name-of-entry-point ... 8-4 

ff:reset-entry-point-table ... 8-4 

top-level:*file-ignore-case* . . . 5-20 

excl:file-older-p file-1 file-2 . . . 3-10 

:find func options* ... 5-7 

lisprfind-symbol ...3-11 

:first . . . 3-6 

excl:fixnump object ... 3-9 

si:flavor-allowed-init-keywords flavor-name . . . 6-24 
flavor-allows-init-keyword-p flavor-name keyword . . . 6-24 
font-close font . . . S-9 
font-open font-file . . . S-9 

ffrforeign-argument descriptor arg-number &key :type :sk!p-bytes ... 8-18 

: foreign-files ( extra-file+ ) ... 8-2 

form-create w h . . . S-2, S-9 

form-draw form . . . S-9 

form-get-point form &optional point . . . S-10 

form-h f .-. . S-2 

formp v . . . S-3 

form-read file-name ... S-10 

form-set-point form point value . . . S-10 

form-w f ... S-2 

form-write form file-name ... S-10 

free-cstruct cstruct-instance . . . 8-24 

funcall instance message &rest arguments . . . 6-23 

:funcall-inside-yourself function &rest args ... 6-35 

funcall-self message arguments* . . . 6-23 

exci:f unction-call-clear ... 7-2 

excl:f unction-call-count function ... 7-2 

exclrf unction-call-list ... 7-1 

excl:f unction-call-report Aoptional number-to-report ... 7-1 
excl:gc ... 2-2 
excl:*gcprint* ... 2-2 

compiler:generate-call-count-code-switch ... 2-5 
compiler:generate-interrupt-check-switch ... 2-5 
exckgenerate-library-pathnames library-root-directory ... 3-11 
:get property-name . . . 6-46 
exci:get-and-zero-call-count function ... 7-2 
get-buttons ... S-10 
get-cursor Aoptional form ... S-10 
get-cursor-position Aoptional point . . . S-10 
ff:get-entry-points name-list address-list Aoptional print ... 8-4 
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system :getenv string ... 4-4 
get-handler-for object operation . . . 6-24 
:get-handler-for operation . . . 6-35 
:getl property-name-list . . . 6-47 
get-machine-type ... S- 10 
get-mouse-bounds &optional pointl point2 . . . S-ll 
get-mouse-position &optional point ... S-ll 
get-real-machine-type ... S-ll 
:gettable-instance-variables . . . 6-25 
get-term-em-rc ... S-ll 
get-viewport Aoptional point ... S-ll 
*grey-halftone* . . . S-19 
:help [command-name] ... 5-2 
top-level:*history* . . . 5-19 
:history [.reverse] [n] ... 5-3 
icon-menu-create icon-vector . . . S-4, S-ll 

icon-menu-create-x icon-vector flag-vector previous :if-error-output-exists ... 4-1 

excl:*ignore-package-name-case* ... 3-2 

lisp:import ... 3-11 

:included-flavors . . . 6-29 

:init init-plist . . . 6-20 

:initabfe-instance-variables . . . 6-26 

init-graphics &optional set-full-graphics-mode-p . . . S-12 

initiaiize-tek-graphics . . . S-12 

:i nit-keywords . . . 6-26 

:inside func . . . 5-11 

inspect — 5-15 

inspect * ...5-15 

inspect ? . . . 5-15 

nnspect - . . . 5-16 

inspect index ...5-15 

inspect name ... 5-15 

inspect object ... 5-15 

inspect print max ... 5-16 

inspect q ... 5-16 

inspect set index form ...5-16 

inspect set name form . . . 5-16 

inspect skip n . . . 5-16 

inspect tree ...5-17 

exckinstancep object . . . 6-21 

instantiate-flavor flavor-name init-plist Aoptional send-init-message-p return-unhandled- 
keywords area ... 6-19 
lisp:intern ...3-11 
:inverse-list . . . 6-40, 6-42 

language language-name language : print : convert-symbol :address iremember-address 
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... 8-6 

:ld file* ...5-10 
top-level:*ld-options* . . . 5-19 

lexpr-funcall-self message arguments* list-of-arguments . . . 6-23 
recompile-flavor flavor-name &optional single-op . . . 6-23 
lexpr-send object message arguments* list-of-arguments ... 6-9 
lexpr-send-self message arguments* list-of-arguments . . . 6-23 
excl::*library-code-cl-pathname* ... 3-9 
excl::*library-code-fasl-pathname* ... 3-9 
*light-grey-halftone* . . . S-19 
line-draw point- 1 point-2 ... S- 12 

line-draw-x point-1 point-2 width draw-last-p bbcom . . . S-12 

lisp:export ...3-11 

lisp:find-symbol ...3-11 

lisp:import ... 3-11 

lisp:intern ...3-11 

lisp:shadow ...3-11 

lisp:shadowing-import ...3-11 

lisp:unexport ...3-11 

lisp:unintern ...3-11 

lisp:unuse-package ...3-11 

lisp:use-package ...3-11 

ff:lisp-value index ... 8-16 

.-list . . . 6-39, 6-42 

system:*load-search-list* ... 3-8 

rlocal name ... 5-8 

make-bbcom &key :srcform :destform :srcpoint :destrect xliprect :halftoneform :rule 

. . . S-3 

make-cstruct name . . . 8-24 

make-display-state . . . S-4 

make-halftoneform &optional patternlist ... S-19 

make-instance flavor-name {init-option value}* . . . 6-18 

make-point x y . . . S-l 

make-rect x y w h ... S-2 

malloc-cstruct name . . . 8-24 

menu-create vector-of-strings . . . S-4, S-12 

menu-create-x vector-of-strings flag-vector previous font . . . S-4, S-12 

menu-destroy menu . . . S-5, S-12 

menu-left ... S-5 

menu-noselect ... S-5 

menu-right ... S-5 

menu-select menu ... S- 13 

method-combination ... 6-31 

mixture defflavor . . . 6-32 

.■moderate ... 5-6 
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:nconc . . . 6-39, 6-42 
:newest . . . 3-6 
:newest-ask-compile ... 3-6 
:newest-do-compi!e . . . 3-6 
no method type . . . 6-41 
:no-vanilla-fla vor . . . 6-29 
:[+|-]number [?] ... 5-3 
:operation-handled-p operation . . . 6-35 
:or . . . 6-39, 6-41, 6-42 
-.ordered-instance-variabies . . . 6-29 
system :os-wait ... 4-1 

exchrun-shell-command command &key : input ... 4-1 

:outside-accessible-instance-variables . . . 6-30 

.■override . . . 6-42 

paint-line bbcom point ... S- 13 

pan-cursor-enable enablep . . . S-13 

pan-disk-enable enablep . . . S-13 

:pass-on .. .6-40,6-42 

•.pass-type ( passing-convention+ ) ... 8-6 

: .-pattern [? | +] ... 5-3 

point-distance point-1 point-2 ... S-13 

point-from-user point ... S-13 

point-max point-1 point-2 . . . S-13 

point-midpoint point-1 point-2 . . . S-13 

point-min point-1 point-2 ... S- 14 

pointp p . . . S-2 

points-to-rect point-1 point-2 . . . S-14 
point-to-row-column point . . . S-14 
point-x p . . . S-l 
point-y p ... S-l 

polygon-draw point-vector ... S-14 

polygon-draw-x point-vector bbcom ... S-14 

polyline-draw point-vector ... S-14 

polyline-draw-x point-vector width closed bbcom . . . S-14 

:pop [n] ... 5-5 

excl:pp name . . . 3-10 

excl:if* test-form then then-form+ ... 3-10 

top-level:*print* . . . 5-20 

:print boolean ... 8-7 

: print-after expr ... 5-1 1 

: print-all expr ... 5-11 

; print-before expr ... 5-11 

top-level:*print-length* . . . 5-20 

top-level:*print-level* . . . 5-20 

-.print-self stream prindepth escape-p . . . 6-34 
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:progn . . . 6-39, 6-42 
top-level:*prompt* ... 5-19 
:property-list . . . 6-47 
si:property-list-mixin . . . 6-46 
protect-cursor recti &optional rect2 ... S- 15 
:prt ... 5-5 

:push-propertyva\ueproperty-name . . . 6-47 
:putprop value property-name . . . 6-47 
exchratiop object ... 3-9 
top-level:*read* . . . 5-20 

rect-areas-differing rectangle-1 rectangle-2 . . . S-15 
rect-areas-outside rectangle-1 rectangle-2 ... S-15 
rect-box-draw rectangle width ... S-15 
rect-box-draw-x rectangle width bbcom ... S-15 
rect-contains-point rectangle point ... S-15 
rect-contains-rect rectangle-1 rectangle-2 ... S-15 
rect-draw rectangle ... S- 16 
rect-draw-x rectangle bbcom . . . S-16 
rect-from-user &optional rectangle ... S-16 
rect-from-user-x minimum-size form &optional rectangle . . . S-16 
rect-h r . . . S-2 

rect-intersect rectangle-1 rectangle-2 &optional rectangle-3 . . . S-16 

rect-lntersects rectangle-1 rectangle-2 . . . S-16 

rect-merge rectangle-1 rectangle-2 &optional rectangle-3 . . . S-16 

rectp v ... S-2 

rect-w r ... S-2 

rect-x r ... S-2 

rect-y r ... S-2 

ff:register-function symbol-or-compiled-function-object &optional index ... 8-15 

ff:register-value value &optional index . . . 8-15 

release-cursor ...S-17 

; remember-address boolean ... 8-7 

top-level:remove-alias &rest names . . . 5-22 

ff:remove-entry-point name-of-entry-point ... 8-4 

:remprop property-name . . . 6-47 

•.required-flavors . . . 6-28 

:required-init-keywords . . . 6-27 

■.required-instance-variables . . . 6-27 

-.required-methods . . . 6-27 

system:*require-search-list* ... 3-9 

:reset ... 5-4 

ff:reset-entry-point-table ... 8-4 
ff:defforeign lisp-name &key -.entry-point ... 8-4 
top-level:*reset-hook* . . . 5-20 
restore-display-state display-state ... S-17 
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:return-type return-type ... 8-7 

ro w-co I u m n-to-rect row column &optional rect . . . S-17 

:run-time-alternatives defflavor . . . 6-32 

save-display-state &optional display-state . . . S-17 

:scont [n] ... 5-14 

★screen-height* . . . S-5 

screen-saver-enable enablep ... S-17 

★screen-width* ... S-5 

self . . . 6-22 

send instance message [argument ...] . . . 6-23 
send object message &rest arguments ... 6-8 
:send-if-handles operation arguments* . . . 6-35 
send-self message arguments* . . . 6-23 
excl :set-case-mode new-mode ... 3-2 
set-cursor form ... S-17 
set-cursor-position point . . . S-17 
set-in-instance instance symbol value . . . 6-24 
set-keyboard-code val ... S-17 
set-machine-type value ... S- 18 

set-mouse-bounds pointl point2 S-18 

set-mouse-position point ... S-18 

:set-property-list list . . . 6-47 

■.settable-instance-variables . . . 6-25 

set-viewport point ... S-18 

lisp:shadow ...3-11 

lisp:shadowing-import ...3-11 

exchshell &optional command ... 4-3 

si :flavor-ailowed-i nit-keywords flavor-name . . . 6-24 

excl:single-floatp object ... 3-9 

si:property-list-mixin . . . 6-46 

shvanilla-flavor . . . 6-34 

:skip n . . . 5-7 

★source-file-type* ...3-11 

:sover ... 5-14 

:special-instance-variables . . . 6-26 
:step [t | nil | function-list] ... 5-13 
★step-print-length* . . . 5-14 
★step-print-level* ...5-14 
string-draw string point ... S-18 
string-draw-raw-x string point bbcom font ... S-18 
string-draw-x string point bbcom font ... S-18 
string-width string font ... S-18 

symeval-in-instance instance symbol &optional no-error-p . . . 6-24 
system :command-line-argument n ... 4-3 
system :command-line-argument-count . . . 4-3 
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system:command-line-arguments ... 4-3 
system rgetenv string :system-libraries ... 8-2 
•.system-libraries ( library+ ) ... 8-2 
system:*load-search-list* ... 3-8 
system :os-wait ... 4-1 
system:*require-search-list* ... 3-9 
terminal-enable enablep ... S- 19 
:top ...5-7 

top-level:alias {name | (name [option ...])} arglist body . . . 5-21 

top-level:*auto-zoom* . . . 5-19 

top-level:*command-char* ... 5-19 

top-level:do-command name &rest arguments . . . 5-22 

top-level:*eval* . . . 5-20 

top-level :*exit-on-eof* . . . 5-19 

top-level:*file-ignore-case* . . . 5-20 

top-level:*history* . . . 5-19 

top-level:*ld-options* . . . 5-19 

top-level:*print* . . . 5-20 

top-level :*print-length* . . . 5-20 

top-level :*print-level* . . . 5-20 

top-level:*prompt* ... 5-19 

top-level:*read* . . . 5-20 

top-level:remove-alias &rest names . . . 5-22 

top-levei:*reset-hook* . . . 5-20 

top-level:*zoom-display* ... 5-8 

top-level:*zoom-print-length* ... 5-8 

top-level:*zoom-print-level* . . . 5-8 

:trace function-or-option-list* ... 5-10 

excl:*trace-output* ... 5-11 

excl:*trace-print-length* ... 5-11 

excl:*trace-print-level* ...5-11 

compiler:trust-declarations-switch ... 2-6 

exckuncompile function-name ... 3-9 

undefflavor flavor . . . 6-22 

undefmethod flavor [type] operation [suboperation] . . . 6-22 

lisp:unexport ...3-11 

lisp:unintern ...3-11 

:untrace [function-list] ... 5-11 

lisp:unuse-package ...3-11 

:up ... 5-7 

:up [n] use-old-combined-methods do-dependents . . . 6-23 
lisp:use-package ...3-11 
excl:username-to-home-di rectory name . . . 4-4 
si:vanilla-flavor . . . 6-34 
: verbose . . . 5-6 
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compiler:verify-argument-count-switch ... 2-6 
compiler:verify-car-cdr-switch . . . 2-6 
compiler:verify-non-generic-switch ... 2-6 
compiler:verify-symbol-value-is-bound-switch . . 
*very-light-grey-halftone* . . . S-19 
video-normal normalp ... S-19 
★view-height* . . . S-5 
★view-width* . . . S-5 
:which-operations . . . 6-34 
★white-halftone** ...S-19 
; wrapper . . . 6-42 
:zoom arguments* ... 5-6 
top-level :*zoom-display* ... 5-8 
top-level:*zoom-print-length* ... 5-8 
top-level:*zoom-print-level* ... 5-8 
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Tektronix 4400 graphics library 


The LISP tek4400-graphics (nicknamed gr ) package permits LISP users to 
directly call functions in the graphics library on the 4400 series machines. The 
LISP interface is nearly identical to the C interface. Please refer to the Graph- 
ics Library documentation in the Workstation Reference Manual for informa- 
tion on what each graphics routine does. Listed below are the LISP function 
names and the reference to the C graphics name in the 4400 Series C Refer- 
ence. 

The tek4400- graphics module can be loaded automatically with COMMON 
LISP require function as in (require ’tek-graph). Once loaded, the graphics 
mode must be initialized by calling the function initialize-tek-graphics which 
sets the *screen* variable. *screen* is the form representing the display bit- 
map. 


A point is a special data type which internally consists of two 16-bit signed 
integers. 

make-point x y [Function] 

■ Returns a point, x and y are integers. 

point-x p 
point-y p 

■ Accesses point p’s x and y coordinates respectively. 

□ To modify the x and y coordinates of a point p, use sett as in (sett 
(point-x p) x2), where x2 is an integer. 


[Function] 

[Function] 


1 

Introduction 


2 

Data 

structures 


2.1 

Points 



Tektronix, Inc. 

S-2 Tektronix 4400 graphics library 


2.2 

Rectangles 


2.3 

Forms 


pointp p [Function] 

■ Returns f if and only if p is a point. 

A rectangle is a special data type internally represented as four 16-bit signed 
integers. 


make-rect x y w h 

■ Returns a rectangle, x, y, w, and h are each integers. 

rect-x r 
rect-y r 
rect-w r 
rect-h r 


[Function] 


[Function] 

[Function] 

[Function] 

[Function] 


■ Accesses rectangle r’s x, y, w, and h corrdinates respectively. 

□ To modify these coordinates of rectangle r, use setf as in (setf (rect-x r) 
x2), where x2 is an integer. 


rectp v 

■ Returns t if and only if v is a rectangle. 


[Function] 


A form is a bitmap. The contents of a form should only be manipulated with 
such functions as bit-bit or paint-line; the fields should never be modified in 
any other way by a user program! Doing so may cause the low level bit-bit 
primitive to overwrite adjacent LISP objects and cause LISP to crash. Forms 
created by the form-create function contain the bitmap in the form (thus unless 
you set *print-array* to nil or set *print-length* to a small value you will not 
want ‘prim’ to ever print a. form value). The form returned by init-graphics 
points to the screen form (which is not in the form itself but which is pointed to 
by the form). Each form begins with a ‘magic’ number to aid type checking. 

form-create w h [Function] 

■ Creates and returns a form. This function is described in the ‘Func- 
tions’ section below. 

□ See the C function FormCreate in §5 of the 4400 Series C Reference. 

form-w f [Function] 

form-h f [Function] 

■ Accesses form f’sw (width) and h (height) dimensions respectively. 
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formp v 

■ Returns t if and only if v is di form. 


[Function] 


A bbcom is a bit-bit command vector. The user constructs the command vector 
and then passes it to such functions as bit-bit or paint-line. The contents of the 
bbcom may be modified, but only with legal values. Fields are: 


srcform 

a form or nil 

destform 

a. form 

srcpoint 

a point 

destrect 

a rect 

cliprect 

a rect 

halftoneform 

a. form or nil 

rule 

afixnum 


make-bbcom &key :srcform tdestlorm :srcpoint :destrect [Function] 
•.cliprect :halftoneform :rule 

■ Returns a bbcom. The default values are 


srcform 

nil 

destform 

*screen* 

halftoneform 

nil 

srcpoint 

(0,0) 

destrect 

(0, 0, *screen-width *, *screen-height*) 

cliprect 

(0,0, *screen-width*, *screen-height*) 

rule 

bb-s if srcform is non-nil or 
bb-one if srcform is nil. 


*screen* names the form for the screen. *screen-width* and *screen- 
height* name the pixel width and height of the screen respectively. 

□ For each of the fields X, there is a bbcom-X function to access that 
field. 

□ To modify a field X, one can use sett for each X as in (sett (bbcom- 
halftoneform form) r2) where form is a form, and r2 is a bbcom rule. 

□ This function replaces the BbcomDefault function in the C graphics 
library. 


2.4 

Bbcoms 
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bbcomp v [ Function ] 

■ Returns t if and only if v is a bbcom. 


2.5 

Display 

states 


A display state holds the complete state of the display (except the screen bit- 
map). 

make-display-state [Function] 

■ Returns a display state. 

display-state-p v [Function] 

■ Returns f if and only if v is a display state. 


2.6 

Menus 


icon-men u-create-x icon-vector flag-vector previous [Function] 

■ Initializes and returns a menu. This function is described in the ‘Func- 
tions’ section below. 

□ See the C function IconMenuCreateX in §5 of the 4400 Series C 
Reference. 

menu-create vector-of-strings [Function] 

■ Initializes and returns a menu. This function is described in the ‘Func- 
tions’ section below. 

□ See the C function MenuCreate in §5 of the 4400 Series C Reference. 

menu-create-x vector-of-strings flag-vector previous font [Function] 

■ Initializes and returns a menu. This function is described in the ‘Func- 
tions’ section below. 

□ See the C function MenuCreateX in §5 of the 4400 Series C Refer- 
ence. 


A menu is a structure containing forms, a bbcom and several other fields. 

icon-menu-create icon-vector [Function] 

■ Initializes and returns a menu. This function is described in the ‘Func- 
tions’ section below. 

□ See the C function IconMenuCreate in §5 of the 4400 Series C Refer- 
ence. 
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menu-destroy menu [Function] 

■ Deallocates a menu. This function is described in the ‘Functions’ sec- 
tion below. 

□ See the C function MenuDestroy in §5 of the 4400 Series C Reference. 


menu-left 

menu-noselect 

menu-right 

■ Constants for the flag vectors of menu structures. 


[Constant] 
[ Constant] 
[Constant] 


bb-zero 

[ Constant] 

bb-s-and-d 

[Constant] 

bb-s-and-not-d 

[ Constant] 

bb-s 

[Constant] 

bb-not-s-and-d 

[ Constant] 

bb-d 

[ Constant] 

bb-s-xor-d 

[Constant] 

bb-s-or-d 

[Constant] 

bb-not-s-and-not-d • 

[Constant] 

bb-not-s-xor-d 

[ Constant] 

bb-not-d 

[Constant] 

bb-s-or-not-d 

[Constant] 

bb-not-s 

[ Constant] 

bb-d-or-not-s 

[Constant] 

bb-not-s-or-not-d 

[Constant] 

bb-one 

[Constant] 

■ These LISP constants are the rules passed to bit-bit and correspond to 
the C constants defined in / lib! include! graphics. h. 


♦screen-height* [Variable] 

♦screen-width* [Variable] 

■ These variables contain the size in pixels, as height and width, of the 
screen bitmap. 

♦view-height* [Variable] 

♦view-width* [Variable] 

■ These variables contain the size in pixels, as height and width, of the 
visible portion of the screen bitmap. 


3 

Rules for - 

bit-bit 


4 

Variables 
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5 

Functions 


The documentation for these functions can be found in §5, ‘Graphics Library 
Reference,’ of the 4400 Series C Reference. The order that the functions are 
listed below is the same order as they appear in that section of the manual, i.e. 
in alphabetical order. Note that some of the functions have been described 
above, and that some functions in the C library have no counterpart in LISP. 
Functions that have no counterpart are functions such as Bbcom Default and 
FormCopy that manifest the unique programming paradigm of C. In the case 
of BbcomDefault, the LISP counterpart is make-bbcom, which both allocates 
and initializes a bbcom object. In C a bbcom would be created by declaring a 
struct BBCOM structure, whereas in LISP a bbcom object must be allocated. In 
the case of FormCopy, the generic LISP function copy-seq subsumes the 
data-specific C function. 

In general the LISP function’s name is generated by a simple transforma- 
tion of the C function name. The C function name is divided just before each 
embedded capital letter, the letter is converted to lower case, and a hyphen is 
inserted at each such division. For example, the C library function Clear- 
Screen becomes the LISP function clear-screen. In some cases the LISP func- 
tion expands abbreviated components in C function names, e.g. the C function 
GetCPosition becomes the LISP function get-cursor-position. 

Certain conventions are observed in describing the arguments to these 
functions. Arguments ending with "p" are predicates. The value nil means 
‘false’ and anything else means ‘true’. Some of the functions that return struc- 
tures take optional arguments (e.g. get-viewport). If the argument is passed to 
the function, then the result value will be stored in that argument, otherwise the 
function will allocate a new structure and return it. 

N.B. All functions check for errors from the library and signal an error if 
an error is detected. Thus functions don’t return if there was an error. If there 
was no error, the functions return the value returned by the C library function, 
converted to an appropriate LISP data type. 

bit-bit bbcom [Function] 

■ Performs the bit-bit command described in the bbcom record. 

□ See the C function BitBIt in §5 of the 4400 Series C Reference. 

char-draw char point [Function] 

■ Draws the character char at point point. 

□ See the C function CharDraw in §5 of the 4400 Series C Reference. 

char-draw-raw-x char point bbcom font [Function] 

■ Draws the character char in font font at point point using the parame- 
ters of the bbcom. 

□ See the C function CharDrawRawX in §5 of the 4400 Series C Refer- 
ence. 
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char-draw-x char point bbcom font [Function] 

■ Draws the character char infant font at point point using the parame- 
ters of the bbcom. The value of point is updated to location at the end of 
the character. 

□ See the C function CharDrawX in §5 of the 4400 Series C Reference. 

char-width char font [Function] 

■ Returns the width in pixels required to draw character char in font font. 

□ See the C function CharFont in §5 of the 4400 Series C Reference. 

circle-draw center radius [Function] 

■ Draws a circle centered at point center of the specified fixnum radius. 

□ See the C function CircleDraw in §5 of the 4400 Series C Reference. 

circle-draw-x center radius width bbcom [Function] 

■ Draws a circle centered at point center of the specified fixnum radius 
using a line of fixnum width onto the form specified by bbcom. 

□ See the C function CircleDrawX in §5 of the 4400 Series C Reference. 

clear-screen [Function] 

■ Clear the screen. 

□ See the C function ClearScreen in §5 of the 4400 Series C Reference. 

cursor-track trackp [Function] 

■ Force cursor to track the mouse if trackp is true. 

□ See the C function CursorTrack in §5 of the 4400 Series C Reference. 

cursor-visible visiblep [Function] 

■ Make cursor visible or invisible based on visiblep 

□ See the C function CursorVisible in §5 of the 4400 Series C Refer- 
ence. 

display-visible visiblep [Function] 

■ Make the display visible or invisible based on visiblep. 

□ See the C function DisplayVisible in §5 of the 4400 Series C Refer- 
ence. 
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event-clear-alarm [Function] 

■ Clears any pending alarms that the process has requested. 

□ See the C function EClearAlarm in §5 of the 4400 Series C Reference. 

event-disable [Function] 

■ Disables event processing. 

□ See the C function EventDisable in §5 of the 4400 Series C Reference. 

event-enable [Function] 

■ Enables event processing. 

□ See the C function EventEnable in §5 of the 4400 Series C Reference. 

event-get-count [Function] 

■ Returns the number of event vvalues in the event buffer waiting to be 
processed. 

□ See the C function EGetCount in §5 of the 4400 Series C Reference. 

event-get-new-count [Function] 

■ Returns the number of event values in the event buffer which have 
occurred since the previous call to this function. 

□ See the C function EGetNewCount in §5 of the 4400 Series C Refer- 
ence. 

event-get-next [Function] 

■ Returns two values: an event- type code and an event value. The 
event-type codes are shown below. 


0 

delta time 

1 

mouse x location 

2 

mouse y location 

3 

key or button pressed 

4 

key or button released 

5 

absolute time 


□ Whenever the keyboard or mouse changes state, a time event is 
generated (either a type 0 or type 5 event) that reports the time of the 
event. This is accompanied by an event value that specifies the actual 
change that occurred. 

□ See the C function EGetNext in §5 of the 4400 Series C Reference. 
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event-get-time [Function] 

■ Returns the time, in milliseconds, since the system was powered up. 

□ See the C function EGetTime in §5 of the 4400 Series C Reference. 

event-set-mouse-interval interval [Function] 

■ Specifies how frequently mouse motion events are to be created if the 
mouse is continuously moving, interval is a.fixnum. 

□ See the C function ESetMInterval in §5 of the 4400 Series C Refer- 
ence. 

event-set-alarm time [Function] 

■ Requests a signal when the specified time, in milliseconds, is reached. 

□ See the C function ESetAlarm in §5 of the 4400 Series C Reference. 

event-set-signal [Function] 

■ Requests the event manager to signal the current process when events 

occur. 

□ See the C function ESetSignal in §5 of the 4400 Series C Reference. 

exit-graphics [Function] 

■ Exit graphics mode. 

□ See the C function ExitGraphics in §5 of the 4400 Series C Reference. 

font-close font [Function] 

■ Releases storage used for the specified font font. 

□ See the C function FontClose in §5 of the 4400 Series C Reference. 

font-open font-file [Function] 

■ Initializes a font from the font file font-file. 

□ See the C function FontOpen in §5 of the 4400 Series C Reference. 

form-draw form [Function] 

■ Displays the form form. 

form-create w h [Function] 

■ Creates and returns di form with width w and height h. 

□ See the C function FormCreate in §5 of the 4400 Series C Reference. 
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form-get-point form &optional point [Function] 

■ Returns the value of a particular point (default (0,0)) in a form. 

□ See the C function FormGetPoint in §5 of the 4400 Series C Refer- 
ence. 

form-read file-name [Function] 

■ Reads a file in Smalltalk ‘form’ format from disk and returns a form 
object initialized from the file. 

□ See the C function Form Read in §5 of the 4400 Series C Reference. 

form-set-point form point value [Function] 

■ Sets the value of a single point in form to value. 

□ See the C function FormSetPoint in §5 of the 4400 Series C Refer- 
ence. 

form-write form file-name [Function] 

■ Writes the form form to the file file-name in Smalltalk format. 

□ See the C function FormWrite in §5 of the 4400 Series C Reference. 

get-buttons [Function] 

■ This returns an integer whose lower three bits are the mouse button 
values (1 = down). 

□ See the C function GetButtons in §5 of the 4400 Series C Reference. 

get-cursor &optional form [Function] 

■ Returns the cursor image bitmap. The image will be stored in form if 
provided. 

□ See the C function GetCursor in §5 of the 4400 Series C Reference. 

get-cursor-position &optional point [Function] 

■ Get the position where the cursor is currently displayed. 

□ See the C function GetCPosition in §5 of the 4400 Series C Reference. 

get-machine-type [Function] 

■ Returns the 4400-series model number as set at machine initialization 
time or by the function set-machine-type. 

□ See the C function GetMachineType in §5 of the 4400 Series C Refer- 
ence. 
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get-real-machlne-type [Function] 

■ Returns the 4400-series model number stored in internal ROM. 

□ See the C function GetRealMachineType in §5 of the 4400 Series C 

Reference. 

get-mouse-bounds &optional pointl point2 [ Function ] 

■ Get the limits on mouse motion. The points will be stored in pointl 
and point2 if provided. 

□ See the C function GetMBounds in §5 of the 4400 Series C Reference. 

get-mouse-position &optional point [Function] 

■ Get the position where the mouse is currently pointing. The point will 
be stored in point if provided. 

□ See the C function GetMPosition in §5 of the 4400 Series C Refer- 
ence. 

get-term-em-rc [Function] 

■ Returns two fixnum values, the number of rows and columns, of the 
terminal emulator. 

□ See the C function GetTermEmRC in §5 of the 4400 Series C Refer- 
ence. 

get-viewport &optional point [Function] 

■ Get the position which the panning hardware is displaying as the upper 
left-hand comer of the display. 

□ See the C function GetViewport in §5 of the 4400 Series C Reference. 

icon-menu-create icon-vector [Function] 

■ Initializes and returns a menu. The argument icon-vector is a vector of 
pointers to forms or nil. 

□ See the C function IconMenuCreate in §5 of the 4400 Series C Refer- 
ence. 

icon-menu-create-x icon-vector flag-vector previous [Function] 

■ Initializes and returns a menu. The argument icon-vector is a vector of 
pointers to forms or nil. The argument flag -vector must be an array of 
(signed-byte 32) elements of the same length as icon-vector. The fixnum 
parameter previous specifies the initial mouse position. 

□ See the C function IconMenuCreateX in §5 of the 4400 Series C 
Reference. 
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init-graphics &optional set-full-graphics-mode-p [Function] 

■ Initialize display for graphics. 

□ See the C function InitGraphics in §5 of the 4400 Series C Reference. 

initialize-tek-graphics [Function] 

■ This function sets the * screen* variable and must be called before 
doing any graphics operations. 

□ This function is equivalent to (setq *screen* (init-graphics nil)). 

line-drawpoint-1 point-2 [Function] 

■ Draws a one-pixel wide line between the points point-1 and point-2. 
Both endpoints are drawn. 

□ See the C function LineDraw in §5 of the 4400 Series C Reference. 

line-draw-x point-1 point-2 width draw-Iast-p bbcom [Function] 

■ Draws a line of width width pixels between the points point- 1 and 
point-2 onto the form specified by bbcom. Both endpoints are drawn 
unless draw-last-p is nil and width is 1 . 

□ See the C function LineDrawX in §5 of the 4400 Series C Reference. 

menu-create vector-of-strings [Function] 

■ Initializes and returns a menu. The argument vector-of-strings must be 
of type (simple-array (simple-string *) (*)). 

□ See the C function MenuCreate in §5 of the 4400 Series C Reference. 

menu-create-x vector-of-strings flag-vector previous font [Function] 

■ Initializes and returns a menu. The argument vector-of-strings must be 
of type (simple-array (simple-string *) (*)). The argument flag-vector 
must be of type (array (signed-byte 32)) and of the same length as vector- 
of-strings. The fixnum argument previous specifies the initial mouse posi- 
tion. Menu items are displayed in font font. 

□ See the C function MenuCreateX in §5 of the 4400 Series C Refer- 
ence. 

menu-destroy menu [Function] 

■ The menu menu is deallocated. 

□ See the C function MenuDestroy in §5 of the 4400 Series C Reference. 
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menu-select menu [Function] 

■ Opens the specified menu and waits for a mouse click or release. 

□ See the C function MenuSelect in §5 of the 4400 Series C Reference. 

paint-line bbcom point [Function] 

■ Paints a line on the display. 

□ See the C function PaintLine in §5 of the 4400 Series C Reference. 

pan-cursor-enable enablep [Function] 

■ Enable screen panning using the cursor if enablep is true. 

□ See the C function PanCursorEnable in §5 of the 4400 Series C 
Reference. 

pan-disk-enable enablep [Function] 

■ Enable screen panning using the joydisk if enablep is true. 

□ See the C function PanDiskEnable in §5 of the 4400 Series C Refer- 
ence. 

point-distance point-1 point-2 [Function] 

■ Returns the distance between the two points. 

□ See the C function PointDistance in §5 of the 4400 Series C Refer- 
ence. 

point-from-user point [Function] 

■ Returns a point selected by the user. 

□ See the C function PointFromUser in §5 of the 4400 Series C Refer- 
ence. 

point-max point-1 point-2 [Function] 

■ Returns the lower right comer of the rectangle defined the the two 
points. 

□ See the C function PointMax in §5 of the 4400 Series C Reference. 

point-midpoint point-1 point-2 [Function] 

■ Returns the midpoint of the line defined by the two points. 

□ See the C function PointMidpoint in §5 of the 4400 Series C Refer- 


ence. 
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point-min point-1 point-2 [Function] 

■ Returns the upper left comer of the rectangle defined by the two points. 

□ See the C function PointMin in §5 of the 4400 Series C Reference. 

point-to-row-column point [Function] 

■ Converts a screen coordinate to the row, column indices which define 
the terminal emulator character cell which contains that point. Returns 
two values: the row and column. 

□ See the C function PointToRC in §5 of the 4400 Series C Reference. 

points-to-rect point-1 point-2 [Function] 

■ Returns the minimum rectangle that contains both points. 

□ See the C function PointsToRect in §5 of the 4400 Series C Refer- 
ence. 

polygon-draw point-vector [Function] 

■ Draws a filled-in polygon defined by the points in the simple-vector 
point-vector. 

□ See the C function PolygonDraw in §5 of the 4400 Series C Refer- 
ence. 

polygon-draw-x point-vector bbcom [Function] 

■ Draws a filled-in polygon defined by the points in the simple-vector 
point-vector onto the destination form specified by bbcom. 

□ See the C function PolygonDrawX in §5 of the 4400 Series C Refer- 
ence. 

polyline-draw point-vector [Function] 

■ Draws a series of line segments connecting the points of the simple- 
vector point-vector using the bbSorD combination rule. The line segments 
are one-pixel wide. 

□ See the C function PoIyLineDraw in §5 of the 4400 Series C Refer- 
ence. 

polyline-draw-x point-vector width closed bbcom [Function] 

■ Draws a series of line segments connecting the points of the simple- 
vector point-vector, each line of width width pixels onto the form specified 
by bbcom. If the fixnum closed is not zero, then a closing line segment is 
drawn from the last to the first point in the vector. The last endpoint is not 
drawn. 
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□ See the C function PolyLineDrawX in §5 of the 4400 Series C Refer- 
ence. 

protect-cursor recti &optional rect2 [Function] 

■ Tell the operating system to respond by removing the cursor from the 
screen if it is in either recti or (optionally) rect2. 

□ See the C function ProtectCursor in §5 of the 4400 Series C Refer- 
ence. 

rect-areas-differing rectangle- 1 rectangle-2 [Function] 

■ Returns the regions of rectangle- 1 that are outside of rectangle-2, and 
the regions of rectangle-2 that are outside of rectangle-1 . 

□ See the C function RectAreasDiffering in §5 of the 4400 Series C 

Reference. 

rect-areas-outside rectangle-1 rectangle-2 [Function] 

■ Returns the regions of rectangle-1 that are outside of rectangle-2. 

□ See the C function RectAreasOutside in §5 of the 4400 Series C 
Reference. 

rect-box-draw rectangle width [Function] 

■ Draws a box of fixnum width pixels around rectangle using the bbSorD 
combination rule. 

□ See the C function RectBoxDraw in §5 of the 4400 Series C Refer- 
ence. 

rect-box-draw-x rectangle width bbcom [Function] 

■ Draws a box of fixnum width pixels around rectangle onto the form 
specified by bbcom. 

□ See the C function RectBoxDrawX in §5 of the 4400 Series C Refer- 
ence. 

rect-contains-point rectangle point [Function] 

■ Returns nil if rectangle does not contain point, otherwise it returns t. 

□ See the C function RectContainsPoint in §5 of the 4400 Series C 
Reference. 

rect-contains-rect rectangle-1 rectangle-2 [Function] 

■ Returns nil unless rectangle-1 contains rectangle-2, in which case it 
returns t. 
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□ See the C function RectContainsRect in §5 of the 4400 Series C 
Reference. 

rect-draw rectangle [Function] 

■ Draws a solid rectangle using the bbS combination rule. 

□ See the C function RectDraw in §5 of the 4400 Series C Reference. 

rect-draw-x rectangle bbcom [Function] 

■ Draws a solid rectangle onto the form specified by bbcom. 

□ See the C function RectDrawX in §5 of the 4400 Series C Reference. 

rect-from-user &optional rectangle [Function] 

■ The region selected by the user is returned. 

□ See the C function RectFromllser in §5 of the 4400 Series C Refer- 
ence. 

rect-from-user-x minimum-size form Aoptional rectangle [Function] 

■ The region selected by the user is returned. The minimum-size argu- 
ment specifies, the minimum size of the region. The form argument speci- 
fies a half-tone form to highlight the selected region. 

□ See the C function RectFromllserX in §5 of the 4400 Series C Refer- 
ence. 

rect-intersect rectangle-1 rectangle-2 &optional rectangle-3 [Function] 

■ Returns (in rectangle-3 if given) the intersection of rectangle-1 and 
rectangle-2. If the rectanges don’t intersect it returns nil. 

□ See the C function Rectlntersect in §5 of the 4400 Series C Reference. 

rect-intersects rectangie-1 rectangle-2 [Function] 

■ Returns t if the rectangles intersect, otherwise nil. 

□ See the C function Rectlntersects in §5 of the 4400 Series C Refer- 
ence. 

rect-merge rectangle-1 rectangle-2 &optional rectangle-3 [Function] 

■ Returns (in rectangle-3 if given) the minimum rectangle that contains 
both rectangle-1 and rectangle-2. 

□ See the C function RectMerge in §5 of the 4400 Series C Reference. 
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release-cursor [Function] 

■ Tell the operating system to restore the cursor if it was removed due to 
a call to protect-cursor. 

□ See the C function ReleaseCursor in §5 of the 4400 Series C Refer- 
ence. 

restore-display-state display-state [Function] 

■ Re-establish the state defined by display-state. 

□ See the C function RestoreDisplayState in §5 of the 4400 Series C 

Reference. 

row-column-to-rect row column &optional rect [Function] 

■ Returns rectange which describes the terminal emulator character cell 
given by row and column. The rectangle will be returned in rect if pro- 
vided. 

□ See the C function RCToRect in §5 of the 4400 Series C Reference. 

save-display-state &optional display-state [Function] 

■ Return the display-state of the current display state. The display-state 
will be stored in display-state if provided. 

□ See the C function SaveDisplayState in §5 of the 4400 Series C 
Reference. 

screen-saver-enable enablep [Function] 

■ Enable the screen saver timeout, which causes the screen to be blanked 
after 10 minutes of keyboard or mouse inactivity. 

□ See the C function ScreenSaverEnable in §5 of the 4400 Series C 

Reference. 

set-cursor form [Function] 

■ Install a new cursor, form must be a 16x16 bit form. 

□ See the C function SetCursor in §5 of the 4400 Series C Reference. 

set-cursor-position point [Function] 

■ Display the cursor at the specified position. 

□ See the C function SetCPosition in §5 of the 4400 Series C Reference. 

set-keyboard-code val [Function] 

■ Tells the keyboard to output either event codes, if val is 0, or ANSI 
character strings, if val is 1 . 



Tektronix, Inc. 

S-18 Tektronix 4400 graphics library 


□ See the C function SetKBCode in §5 of the 4400 Series C Reference. 

set-machine-type value [Function] 

■ Sets the machine type to the fixnum value. 

□ See the C function SetMachineType in §5 of the 4400 Series C Refer- 
ence. 

set-mouse-bounds pointl point2 [Function] 

■ Set the limits on mouse motion to be the rectangle defined by the upper 
left point pointl and the lower right point point2. 

□ See the C function SetMBounds in §5 of the 4400 Series C Reference. 

set-mouse-position point [Function] 

■ Position the mouse at the specified position. 

□ See the C function SetMPosition in §5 of the 4400 Series C Reference. 

set-viewport point [Function] 

■ Set the panning hardware to display the upper left-hand comer of the 
display at the specified point. 

□ See the C function SetViewport in §5 of the 4400 Series C Reference. 

string-draw string point [Function] 

■ Draws the simple-string string using the default font starting at the 
specified point. 

□ See the C function StringDraw in §5 of the 4400 Series C Reference. 

string-draw-raw-x string point bbcom font [Function] 

■ Draws the simple-string string using font font starting at the specified 
point onto the form specified by bbcom. 

□ See the C function StringDrawRawX in §5 of the 4400 Series C Refer- 
ence. 

string-draw-x string point bbcom font [Function] 

■ Draws the simple-string string using font font starting at the specified 
point onto the form specified by bbcom. 

□ See the C function StringDrawX in §5 of the 4400 Series C Reference. 

string-width string font [Function] 

■ Returns the width in pixels of the simple-string string in font font. 

□ See the C function StringWidth in §5 of the 4400 Series C Reference. 


D-02 -03-02 (26 11- 



Tek Common Lisp 
T ektronix 4400 graphics library S-1 9 


terminal-enable enablep [Function] 

■ Enable the terminal emulator if enablep is true. The previous mode is 
returned (t for enabled, nil for disabled). 

□ See the C function TerminalEnable in §5 of the 4400 Series C Refer- 
ence. 

video-normal normalp [Function] 

■ Set display to white on black if normalp is nil, and to black on white 
otherwise. 

□ See the C function VideoNormal in §5 of the 4400 Series C Reference. 


Tek COMMON Lisp includes a function for creating halftone forms, and several 
variables that represent common halftone forms. 

make-halftoneform &optional patternlist [Function] 

■ Make a halftone which has the given pattern in it. patternlist is nor- 
mally a list of sixteen 16-bit signed integers. If patternlist has fewer than 
sixteen integers, then the whole pattern is repeated as many times as is 
necessary to get sixteen integers. 


*black-halftone* 

[Variable] 

*dark-grey-halftone* 

[Variable] 

*grey-halftone* 

[Variable] 

*light-grey-halftone* 

[Variable] 

★very-light-grey-halftone* 

[Variable] 

★white-halftone** 

[Variable] 


6 

Halftone 

forms 


■ Various common halftone forms 




Index 




Index 


+ variable 5-20 
++ variable 5-20 
+++ variable 5-20 
- variable 5-21 
/ variable 5-21 
//variable 5-21 
III variable 5-21 
* variable 5-21 
*★ variable 5-21 
*** variable 5-21 


:abstract-flavor defflavor option 6-3 1 
Accessing slots (§8.8.1) 8-22 
:accessor-prefix defflavor option 6-30 
Adding new top-level commands (§5.12) 5-21 
:address keyword 8-7 
’.after method type 6-41 
top-level:alias macro 5-21 
:aliases top-level command 5-9 
’.alias-flavor defflavor option 6-3 1 
*all-flavor-names* variable 6-17 
Allocating and freeing cstructs (§8.8.3) 8-23 
:and method type 6-41,6-42 
:and method-combination type 6-39 
.•append method type 6-42 
•.append method-combination type 6-39 
•.arg-checking keyword 8-6 
Argument-passing synopsis (§8.9) 8-26 
■.arguments keyword 8-6 
Arrays (§2.2) r-2 
Autoloading (§3.4) 3-9 
top-level:*auto-zoom* variable 5-19 


bbcomp function S-4 
Bbcoms (§2.4) S-3 
bb-d constant S-5 
bb-d-or-not-s constant S-5 
bb-not-d constant S-5 


bb-not-s constant S-5 
bb-not-s-and-d constant S-5 
bb-not-s-and-not-d constant S-5 
bb-not-s-or-not-d constant S-5 
bb-not-s-xor-d constant S-5 
bb-one constant S-5 
bb-s constant S-5 
bb-s-and-d constant S-5 
bb-s-and-not-d constant S-5 
bb-s-or-d constant S-5 
bb-s-or-not-d constant S-5 
bb-s-xor-d constant S-5 
bb-zero constant S-5 
’.before method type 6-41 
exchbignump function 3-9 
bit-bit function S-6 
★black-halftone* variable S-19 
’.bottom keyword 5-7 
Break levels (§5.5) 5-4 
•.break message 6-35 
: break-after keyword 5-11 
ibreak-all keyword 5-11 
ibreak-before keyword 5-11 
’.brief keyword 5-6 

C structures (§8.8) 8-20 
•.call search-list keyword 3-7 
’.case method-combination type 6-40 
•.after method type 6-41 
land method type 6-41, 6-42 
‘.append method type 6-42 
•.before method type 6-41 
icombined method type 6-42 
•.default method type 6-41 
:inverse-list method type 6-42 
’.list method type 6-42 
mconc method type 6-42 
no method type method type 6-41 
lor method type 6-41, 6-42 
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•.override method type 6-42 
:pass-on method type 6-42 
:progn method type 6-42 
•.wrapper method type 6-42 
Case preference (§3.1.3) 3-3 
Case sensitivity of input (§5.2.1) 5-2 
:cf top-level command 5-9 
Changing a flavor (§6.12.2) 6-46 
Changing case modes (§3.1.1) 3-3 
char-draw function S-6 
char-draw-raw-x function S-6 
char-draw-x function S-7 
char-width function S-7 
exchchdir function 4-3 
circle-draw function S-7 
circle-draw-x function S-7 
clear-screen function S-7 
Closures (§2.1) r-2 
-.combined method type 6-42 
Command and expression history (§5.4) 5-3 
top-level:*command-char* variable 5-19 
system :command-line-argument function 4-3 
system :command-line-argument-count function 
4-3 

system :command-line-arguments function 4-3 
Commands and expressions (§5.2.2) 5-2 
Comments and suggestions (§3) p-2 
Compatibility (§3.1.2) 3-3 
Compiled code (§3.1.4) 3-4 
excl:compile-file-if-needed function 3-10 
compile-flavor-methods macro 6-23 
The compiler (§2.4) 2-4 
compiler:declared-fixnums-remain-fixnums-switch 
variable 2-5 

compiler:*do-call-counts* variable 7-2 
compiler:generate-call-count-code-switch variable 
2-5 

compiler:generate-interrupt-check-switch variable 
2-5 

compilertrust-declarations-switch variable 2-6 
cornpiler:verify-argument-count-switch variable 
2-6 

compiler:verify-car-cdr-switch variable 2-6 
compiler:verify-non-generic-switch variable 2-6 
compiler:verify-symbol-value-is-bound-switch vari- 
able 2-6 

; condition keyword 5-11 
continue top-level command 5-5 


Conventions for passing arguments (§8.4) 8-9 
: convert-symbol keyword 8-7 
ff:convert-to-!ang function 8-4 
Copying instances (§6.14) 6-47 
:current top-level command 5-7 
excl:*current-case-mode* variable 3-2 
exclrcurrent-directory function 4-3 
cursor-track function S-7 
cursor-visible function S-7 


•.daemon method-combination type 6-38 
:daemon-with-and method-combination type 
6-38 

:daem on-wit h-or method-combination type 6-38 
:daemon-with-override method-combination type 
6-38 

*dark-grey-halftone* variable S-19 
Data structures (§2) S-l 
Datatypes (§2.1) 2-1 
Declarations and optimizations (§2.4.2) 2-5 
compiler:declared-fixnums-remain-fixnums-switch 
variable 2-5 

•.default method type 6-41 
:default-handler defflavor option 6-29 
:default-init-plist defflavor option 6-26 
ff:defcstruct macro 8-21 
defflavor macro 6-17 
Defflavor options (§6.8) 6-25 
ff:defforeign function 8-6 
:address keyword 8-7 
:arg-checking keyword 8-6 
-.arguments keyword 8-6 
: convert-symbol keyword 8-7 
•.entry-point keyword 8-6 
language keyword 8-7 
:pass-type keyword 8-6 
:print keyword 8-7 
: remember-address keyword 8-7 
; return-type keyword 8-7 
ff:defforeign-list macro 8-8 
Defining a foreign function to LISP (§8.3) 8-5 
Defining and calling LISP functions from foreign 
code (§8.6) 8-14 
defmethod macro 6-17 
ff:defun-c-callable macro 8-17 
defwhopper macro 6-22 
defwrapper macro 6-21 
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describe message 6-34 
describe-flavor function 6-25 
Display states (§2.5) S-4 
display-state-p function S-4 
display-visible function S-7 
:dn keyword 5-7 
:dn top-level command 5-7 
compiler:*do-call-counts* variable 7-2 
top-level :do-command function 5-22 
documentation defflavor option 6-33 
exckdumplisp function 4-4 


: entry-point keyword 8-6 
Environment functions (§4.2) 4-3 
:error top-level command 5-5 
Errors (§3.2) 3-4 
excl rerrorset macro 3-4 
top-level :*eval* variable 5-20 
:eval-inside-yourself message 6-35 
event-clear-alarm function S-8 
event-disable function S-8 
event-enable function S-8 
event-get-count function S-8 
event-get-new-count function S-8 
event-get-next function S-8 
event-get-time function S-9 
event-set-alarm function S-9 
event-set-mouse-interval function S-9 
event-set-signal function S-9 
Example (§3.3.2) 3-7 
excl:bignump function 3-9 
exckchdir function 4-3 
excl:compile-file-if-needed function 3-10 
excl:*current-case-mode* variable 3-2 
excl:current-directory function 4-3 
excl:dumplisp function 4-4 
exckerrorset macro 3-4 
excl:exit function 4-4 
excl:file-older-p function 3-10 
excl dixnump function 3-9 
excl:function-call-clear function 7-2 
excl:function-call-count function 7-2 
excl:function-call-list function 7-1 
excl:function-call-report function 7-1 
exchgc function 2-2 
excl:*gcprint* variable 2-2 
excl:generate-library-pathnames function 3-11 


excl:get-and-zero-call-count function 7-2 
exckif* macro 3-10 

excl:*ignore-package-name-case* variable 3-2 
excl:instancep function 6-21 
excl::*library-code-cl-pathname* variable 3-9 
excl::*library-code-fasl-pathname* variable 3-9 
excl:pp macro 3-10 
exckratiop function 3-9 
excl: run-shell-command function 4-1 
excl:set-case-mode function 3-2 
exckshell function 4-3 
excl :single-floatp function 3-9 
excl:*trace-output* variable 5-11 
excl:*trace-print-length* variable 5-11 
excl:*trace-print-level* variable 5-11 
excl :uncompile function 3-9 
excl:username-to-home-directory function 4-4 
excl :exit function 4-4 
:exit top-level command 5-10 
exit-graphics function S-9 
top-level:*exit-on-eof* variable 5-19 
lisp :export function 3-11 
Extensions (Chapter 3) 3-1 


ff:convert-to-lang function 8-4 
ff:defcstruct macro 8-21 
ff:defforeign function 8-6 
•.address keyword 8-7 
:arg-checking keyword 8-6 
; arguments keyword 8-6 
: convert-symbol keyword 8-7 
; entry-point keyword 8-6 
: language keyword 8-7 
: pass-type keyword 8-6 
:print keyword 8-7 
: remember-address keyword 8-7 
: return-type keyword 8-7 
ff:defforeign-list macro 8-8 
ff:defun-c-callable macro 8-17 
ffdoreign-argument function 8-18 
ff:get-entry-points function 8-4 
ff:Iisp-value function 8-16 
ff:register-function function 8-15 
ff:register-value function 8-15 
ff:remove-entry-point function 8-4 
ff:reset-entry-point-table function 8-4 
File types (§2.4.1) 2-4 
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top-level:*file-ignore-case* variable 5-20 
excl :file-older-p function 3-10 
:find top-level command 5-7 
:dn keyword 5-7 
:skip keyword 5-7 
:up keyword 5-7 
lisp:find-symbol function 3-1 1 
‘.first search-list keyword 3-6 
exchfixnump function 3-9 
Flavor families (§6.9) 6-33 
Flavor functions (§6.7) 6-17 
si:flavor-allowed-init-keywords function 6-24 
flavor-allows-init-keyword-p function 6-24 
Flavors (Chapter 6) 6-1 
font-close function S-9 
font-open function S-9 
Foreign functions (Chapter 8) 8-1 
ff:foreign-argument function 8-18 
; foreign-files keyword 8-2 
Format of the manual (§1.1) 1-1 
form-create function S-2, S-9 
form-draw function S-9 
form-get-point function S-10 
form-h function S-2 
formp function S-3 
form-read function S-10 
Forms (§2.3) S-2 
form-set-point function S-10 
form-w function S-2 
form-write function S-10 
free-cstruct function 8-24 
funcall function 6-23 
:funcalHnside-yourself message 6-35 
funcall-self macro 6-23 
Functionality (§2) r-2 
excl:function-call-clear function 7-2 
excl:function-call-count function 7-2 
excl :f unction-call-list function 7-1 
excl :f unction-call-report function 7-1 
Functions (§5) S-6 


exckgc function 2-2 
excl:*gcprint* variable 2-2 
compiler:generate-call-count-code-switch variable 
2-5 

compiler:generate-interrupt-check-switch variable 
2-5 


exckgenerate-library-pathnames function 3-11 
Generic operations (§6.3) 6-6 
Generic operations in LISP (§6.4) 6-8 
:get message 6-46 

excl:get-and-zero-call-count function 7-2 
get-buttons function S-10 
get-cursor function S- 1 0 
get-cursor-position function S-10 
ff:get-entry-points function 8-4 
system : g etenv function 4-4 
get-handler-for function 6-24 
:get-handler-for message 6-35 
:getl message 6-47 
get-machine-type function S-10 
get-mouse-bounds function S- 1 1 
get-mouse-position function S-ll 
get-real-machine-type function S- 1 1 
:gettable-instance-variables defflavor option 
6-25 

get-term-em-rc function S- 1 1 
Getting help (§5.3) 5-2 
get-viewport function S-l l 
★grey-halftone* variable S-19 . 


Halftone forms (§6) S-19 
:help top-level command 5-2 
History (§2) p-1 
:history top-level command 5-3 
top-level:*history* variable 5-19 
How foreign-called LISP functions get arguments 
(§8.7) 8-17 

How to compile functions (§1.6) 1-4 
How to exit LISP (§1.5) 1-3 
How to run LISP (§1.4) 1-3 


icon-menu-create function S-ll, S-4 
icon-menu-create-x function S-ll, S-4 
excl :if* macro 3-10 

excl:*ignore-package-name-case* variable 3-2 
Image functions (§4.3) 4-4 
Implementation (Chapter 2) 2-1 
Implementing flavors (§6.12) 6-44 
lisp:import function 3-11 
:included-flavors defflavor option 6-29 
:init message 6-20 
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:initable-instance-variables defflavor option 
6-26 

init-graphics function S-12 
Initialization (§5.1) 5-1 
initialize-tek-graphics function S-12 
:init-keywords defflavor option 6-26 
Input/output (§2.3) r-2 
:inside keyword 5-11 
inspect function 5-15 

inspect top-level command 5-15, 5-16, 5-17 
The inspector (§5. 10) 5-14 
exckinstancep function 6-21 
instantiate-flavor function 6- 1 9 
Interaction (§5.2) 5-1 
lisp:intern function 3-1 1 
Internal functions (§2.5) 2-7 
Introduction (§1) S-l 
(Chapter 1) 1-1 
'.inverse-list method type 6-42 
:inverse-list method-combination type 6-40 

Keeping abreast (§5) p-4 


The language (§1) p-1 
'.language keyword 8-7 
:ld top-level command 5-10 
top-leve!:*ld-options* variable 5-19 
lexpr-funcall-self macro 6-23 
lexpr-send macro 6-9 
lexpr-send-self macro 6-23 
excl::*library-code-cl-pathname* variable 3-9 
excl::*library-code-fasl-pathname* variable 3-9 
* light-grey-halftone* variable S-19 
line-draw function S-12 
iine-draw-x function S-12 
lisp:export function 3-11 
lisp:find-symbol function 3-1 1 
lisp :import function 3-11 
lisp:intern function 3-11 
lisp:shadow function 3-1 1 
lisp:shadowing-import function 3-11 
lisp:unexport function 3- 1 1 
lisprunintem function 3-11 
lisp:unuse-package function 3- 1 1 
lisp:use-package function 3- 1 1 
ff:lisp-value function 8-16 


.'list method type 6-42 
:list method-combination type 6-39 
Load errors (§8.2) 8-3 
load function 8-2 , 

'.foreign-files keyword 8-2 
: system-libraries keyword 8-2 
The loader (§8.1.1) 8-2 
Loading foreign code (§8.1) 8-2 
Loading library functions (§8.1.2) 8-3 
system:*load-search-list* variable 3-8 
:local top-level command 5-8 


make-bbcom function S-3 

make-cstruct function 8-24 

make-display-state function S-4 

make-halftoneform function S-19 

make-instance function 6-18 

make-point function S-l 

make-rect function S-2 

malloc-cstruct function 8-24 

menu-create function S-12, S-4 

menu-create-x function S-12, S-4 

menu-destroy function S-12, S-5 

menu-left constant S-5 

menu-noselect constant S-5 

menu-right constant S-5 

Menus (§2.6) S-4 

menu-select function S-l 3 

Merging pathnames (§2.3.2) 2-3 

Method combination (§6.11) 6-35 

-.method-combination defflavor option 6-3 1 

Miscellaneous commands (§5.7) 5-9 

Miscellaneous features (§3) r-2 

Miscellaneous functions and symbols (§3.5) 3-9 

Mixing flavors (§6.6) 6-13 

'.mixture defflavor option 6-32 

■.moderate keyword 5-6 

Modularity (§6.2) 6-3 

:nconc method type 6-42 
:nconc method-combination type 6-39 
New features in this release (§1) r-1 
'.newest search-list keyword 3-6 
:newest-ask-compile search-list keyword 3-6 
:newest-do-compile search-list keyword 3-6 
no method type method type 6-41 
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A note on portability (§2.6) 2-8 
:no-vanilla-flavor defflavor option 6-29 
:[+| -]nu mbe r top-level command 5-3 


Objects (§6.1) 6-1 

Operating-system interface (Chapter 4) 4-1 
:operation-handled-p message 6-35 
:or method type 6-41,6-42 
:or method-combination type 6-39 
Order of definition (§6.12.1) 6-45 
-.ordered-instance-variables defflavor option 
6-29 

system :os-wait function 4-1 
Other documents (§1.3) 1-2 
An outline of the manual (§1.2) 1-2 
:outside-accessible-instance-variables defflavor 
option 6-30 

:override method type 6-42 


Packages (Chapter 9) 9-1 
Packages in Tek COMMON LISP (§9.1) 9-1 
paint-line function S-13 
pan-cursor-enable function S-13 
pan-disk-enable function S-13 
Parsing pathnames (§2.3.1) 2-2 
Passing arrays of strings from LISP to C (§8.5) 
8-12 

:pass-on method type 6-42 
:pass-on method-combination type 6-40 
:pass-type keyword 8-6 
Pathnames (§2.3) 2-2 
::pattern top-level command 5-3 
point-distance function S-13 
Pointers, embedded structures, and arrays (§8.8.4) 
8-24 

point-from-user function S-13 
point-max function S-13 
point-midpoint function S-13 
point-min function S-14 
pointp function S-2 
Points (§2.1) S-l 
points-to-rect function S-14 
point-to-row-column function S-14 
point-x function S-l 
point-y function S-l 
polygon-draw function S-14 


polygon-draw-x function S-14 
polyline-draw function S-14 
polyline-draw-x function S-14 
:pop top-level command 5-5 
Portability issues (§8.8.5) 8-26 
excl :pp macro 3-10 
Preface (Prependix p) p-1 
:print keyword 8-7 
top-levei:*print* variable 5-20 
; print-after keyword 5-11 
: print-all keyword 5-11 
: print-before keyword 5-11 
top-level:*print-length* variable 5-20 
top-level:*print-ievel* variable 5-20 
•.print-self message 6-34 
Profiling (Chapter 7) 7-1 
:progn method type 6-42 
:progn method-combination type 6-39 
top-level:*prompt* variable 5-19 
Property list operations (§6.13) 6-46 
•.property-list message 6-47 
si:property-list-mixin flavor 6-46 
protect-cursor function S-15 
:prt top-level command 5-5 
:push-propertyproperty-name message 6-47 
iputprop message 6-47 


exckratiop function 3-9 
top-leve!:*read* variable 5-20 
Reader case modes (§3.1) 3-1 
recompile-flavor function 6-23 
Rectangles (§2.2) S-2 
rect-areas-differing function S-15 
rect-areas-outside function S-15 
rect-box-draw function S-15 
rect-box-d raw-x function S-15 
rect-contains-point function S-15 
rect-contains-rect function S-15 
rect-draw function S-16 
rect-draw-x function S-16 
rect-f rom-user function S-16 
rect-from-user-x function S-16 
rect-h function S-2 
rect-i ntersect function S- 1 6 
rect-intersects function S-16 
rect-merge function S-16 
rectp function S-2 
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rect-w function S-2 
rect-x function S-2 
rect-y function S-2 
ffrregister-function function 8-15 
ff:register-value function 8-15 
Release 1.4 notes for Tektronix Workstations 
(Prependix r) r- 1 
release-cursor function S-17 
: remember-address keyword 8-7 
top-level:remove-alias function 5-22 
ff:remove-entry-point function 8-4 
:remprop message 6-47 
Reporting bugs (§4) p-2 
•.required-flavors defflavor option 6-28 
:required-init-keywords defflavor option 6-27 
:required-instance-variables defflavor option 
6-27 

•.required-methods defflavor option 6-27 
system:*require-search-list* variable 3-9 
:reset top-level command 5-4 
ff :reset-entry-point-table function 8-4 
top-level:*reset-hook* variable 5-20 
restore-display-state function S-17 
:return-type keyword 8-7 
row-column-to-rect function S-17 
Rules for bit-bit (§3) S-5 
excl:run-shell-command function 4-1 
:run-time-alternatives defflavor option 6-32 


A sample initialization file (§5.13) 5-23 
save-display-state function S-17 
:scont top-level command 5-14 
♦screen-height* variable S-5 
screen-saver-enable function S-17 
♦screen-width* variable S-5 
Search lists (§3.3) 3-5 
self variable 6-22 
send function 6-8 
send macro 6-23 
:send-if-handles message 6-35 
send-self macro 6-23 
excl:set-case-mode function 3-2 
set-cursor function S-17 
set-cursor-position function S-17 
set-in-instance function 6-24 
set-keyboard-code function S-17 
set-machine-type function S-18 


set-mouse-bounds function S-18 
set-mouse-position function S-18 
:set-property-list message 6-47 • 

■.settable-instance-variables defflavor option 
6-25 

set-viewport function S-18 
lisp:shadow function 3-11 
lisp:shadowing-import function 3-11 
exckshell function 4-3 
si:flavor-allowed-init-keywords function 6-24 
Simple use of flavors (§6.5) 6-9 
exchsingle-floatp function 3-9 
si:property-list-mixin flavor 6-46 
si:vanilla-flavor flavor 6-34 
:skip keyword 5-7 
♦source-file-type* variable 3-11 
:sover top-level command 5-14 
:special-instance-variables defflavor option 
6-26 

Stack commands (§5.6) 5-6 
:step top-level command 5-13 
The stepper (§5.9) 5-13 
♦step-print-iength* variable 5-14 
♦step-print-level* variable 5-14 
Storage allocation (§2.2) 2-2 
Storage allocation for cstructs (§8.8.2) 8-22 
string-draw function S-18 
string-draw-raw-x function S-18 
string-draw-x function S- 1 8 
string-width function S-18 
Structure (§3.3.1) 3-5 
Subprocess functions (§4.1) 4-1 
Symbols in the excl package (§9.2) 9-2 
symeval-in-instance function 6-24 
system :command-line-argument function 4-31 
system :command-line-argument-count function 
4-3 

system :command-line-arguments function 4-3. 
system :getenv function 4-4 
: system-libraries keyword 8-2 
system:*load-search-list* variable 3-8 
system :os-wait function 4-1 
system:*require-search-list* variable 3-9 
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terminal-enable function S- 19 q 
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:top keyword 5-7 
Top level (Chapter 5) 5-1 
Top-level forms (§2.4.3) 2-7 
Top-level variables (§5.11) 5-19 
top-level:alias macro 5-21 
top-level:*auto-zoom* variable 5-19 
top-level:*command-char* variable 5-19 
top-level :do-command function 5-22 
top-level:*eval* variable 5-20 
top-leve!:*exit-on-eof* variable 5-19 
top-level:*file-ignore-case* variable 5-20 
top-level:*history* variable 5-19 
top-level:*ld-options* variable 5-19 
top-level:*print* variable 5-20 
top-level:*print-length* variable 5-20 
top-level:*print-level* variable 5-20 
top-level:*prompt* variable 5-19 
top-level:*read* variable 5-20 
top-level:remove-alias function 5-22 
top-level:*reset-hook* variable 5-20 
top-level:*zoom-display* variable 5-8 
top-level:*zoom-print-length* variable 5-8 
top-leve!:*zoom-print-level* variable 5-8 
:trace top-level command 5-10 
: break-after keyword 5-11 
: break-all keyword 5-11 
: break-before keyword 5-11 
: condition keyword 5-11 
: inside keyword 5-11 
: print-after keyword 5-11 
: print-all keyword 5-11 
; print-before keyword 5-11 
excl:*trace-output* variable 5-1 1 
excl:*trace-prinl -length* variable 5-11 
excl:*trace-print-level* variable 5-11 
The tracer (§5.8) 5-10 
compiler:tnjst-declarations-switch variable 2-6 


lisp :use-package function 3-11 
exci:username-to-home-directory function 4-4 


Vanilla flavor (§6.10) 6-34 
si:vanilla-flavor flavor 6-34 
Variables (§3.3.3) 3-8 
(§4) S-5 

•.verbose keyword 5-6 
compiler:verify-argument-count-switch variable 
2-6 

compiler:verify-car-cdr-switch variable 2-6 
compiler:verify-non-generic-switch variable 2-6 
compiler:verify-symbol-value-is-bound-switch vari- 
able 2-6 

*very-light-grey-halftone* variable S-19 
video-normal function S-19 
★view-height* variable S-5 
★view-width* variable S-5 


twhich-operations message 6-34 
★white-halftone** variable S-19 
wrapper method type 6-42 


:zoom top-level command 5-6 
: bottom keyword 5-7 
:brief keyword 5-6 
: moderate keyword 5-6 
:top keyword 5-7 
•.verbose keyword 5-6 
top-level:*zoom-display* variable 5-8 
top-level:*zoom-print-length* variable 5-8 
top-level:*zoom-print-level* variable 5-8 


exchuncompiie function 3-9 
undefflavor function 6-22 
undefmethod macro 6-22 
lisp:unexport function 3- 1 1 
lisp :unintern function 3-11 
:untrace top-level command 5-11 
lisprunuse-package function 3- 1 1 
tup keyword 5-7 
:up top-level command 5-7 
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2 Functionality r-2 

2.1 Closures r-2 
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Release 1 .4 notes for Tektronix Workstations 


This chapter describes release 1.4 of Tek COMMON LISP for the Tektronix 
Workstations. The information provided here pertains specifically to this 
release — general information on the topics discussed here may be found in the 
Tek COMMON USP User Guide and in Common Lisp: The Language. 


An extension to COMMON LISP, the foreign-function interface, is included in 
this release. The interface allows LISP to call C functions, and allows C func- 
tions to call back to LISP. A C structures package is part of the foreign func- 
tion interface. Also included is a file which provides macros for C code to 
correctly convert LISP objects to C data formats is also included. It is called 
lisp68k.h and is located in the lib/misc directory on the distribution tape. This 
directory will usually have absolute name / common-lisp! lib. You should con- 
sult your system manager for the exact location on your system. The foreign- 
function interface is documented in Chapter 8 of Tek COMMON LISP User 
Guide. 

Other new functions for interfacing with the operating system have been 
added. The most powerful is run-shell-command. All are documented in 
Chapter 4. 

Various new functions and macros have been added to fill in some gaps in 
the COMMON Lisp specification. Additions include tests for more data types 
and a ‘keyword-style’ if construct. All are documented in Chapter 3. 

Other new features include: 

1 In order to make explicit the difference between pure COMMON LISP code 
(as specified in Common Lisp) and the extensions found in Tek COMMON 
LISP, the location of many symbols has been changed. Chapter 9 of Tek 
COMMON Lisp User Guide describes this change in detail. Please note 
that files compiled under earlier versions of Tek COMMON LISP must be 
recompiled with this version. 

2 There is now an inspector accessable through the The inspector is 
described in Chapter 5 of Tek COMMON LISP User Guide. 

3 The compiler optimizations can be better controlled by the user. See sec- 
tion 1.5 of Tek COMMON Lisp User Guide for details. 
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,4 notes for Tektronix Workstations 

Certain limitations on the functionality of L are noted here. 


It is not possible to compile functional objects (closures) created by interpre- 
tive evaluation of the function special form. For example, the functional value 
of symbol closure-sym below cannot be compiled in this release, and an error 
will be signalled by the compile function. 

<cl> (setf ( symbol- function 'closure-sym) 

(let ( (local -var 0) ) 

(function 

(lambda (bound- var) 

(+ bound-var local-var) ) ) ) ) 

<cl> (compile 'closure-sym) 


The functions bit, sbit, char and schar are treated just like aref in that no 
effort is made to ensure that the first argument is of the correct type. It is an 
error, although it is not signalled, to provide a sequence argument of the wrong 
type. 


Because of limitations of the operating system, the functions read-char-no 
hang and listen may hang, so they should be avoided. 


When the Tek COMMON LISP image is invoked, it will initially attempt to allo- 
cate the maximum heap space for which it was configured (see the ‘Installation 
guide’ for details). If, however, it is unable to allocate the requested amount of 
heap space, it will attempt to allocate 256 kbytes less. The image will repeat- 
edly attempt to allocate space, each time asking for 256 kbytes less space, until 
the amount of space requested is allocatable or until the mimimum request of 3 
Mbytes is reached. If the miminum of 3 Mbytes cannot be allocated, the image 
terminates with an error message. 
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